fix: Clean up agent YAML frontmatter and add standards (#156)

* chore: bump version to v0.8.0

* chore: update version to 0.7.1 instead of 0.8.0

* docs: expand comparison table with Oh My OpenCode and additional features

* backup: development context before reorganization

* refactor(context): reorganize development folder

- Remove 7 duplicate files (ui/design files exist in ui/web/)
- Remove 2 redundant READMEs (use navigation.md instead)
- Move react-patterns.md to frontend/react/
- Create frontend/react/navigation.md
- Update 4 navigation files (development, ui, frontend, frontend/react)
- Update developer profile (4 path changes: ui-styling-standards, design-systems, design-assets, animation-patterns)
- Update 3 core context files (visual-development.md, design-iteration.md, file-locations.md)

Result: 29 context files (down from 36), no duplicates, clean structure

Refs: REORGANIZATION_PLAN.md, REORGANIZATION_SUMMARY.md

* docs(context): add frontend delegation guide

- Create when-to-delegate.md with clear decision criteria
- Decision matrix for when to delegate vs. handle directly
- Common patterns and examples
- Red flags and green flags
- Frontend-specialist capabilities reference
- Update frontend and development navigation files

Helps orchestrators decide when to delegate UI work to frontend-specialist subagent.

* feat: enhance developer and advanced profiles with UI, development, and system builder context

- Developer profile: Add UI/UX patterns, development principles, design systems, React patterns, animation patterns, styling standards, and design assets
- Full profile: Add same UI/development context as developer profile for consistency
- Advanced profile: Add comprehensive system builder context including templates, guides, context system standards, and repository management context
- Update profile descriptions to reflect new capabilities
- All context files verified to exist and are properly referenced

* fix: remove duplicate context entries with incorrect paths

- Remove duplicate design-assets, ui-styling-standards, clean-code, animation-patterns, design-systems, react-patterns, and api-design entries that pointed to wrong paths
- Remove non-existent development-readme and mastra-ai-readme entries
- Keep only correct entries with proper file paths
- All registry paths now validated and correct

* feat: add add-context command to registry and all profiles

- Register add-context command in registry.json
- Add command:add-context to all 5 profiles (essential, developer, business, full, advanced)
- Update add-context.md to mention external-context files in .tmp/ directory
- Fix command dependencies to use context IDs instead of full paths
- All registry paths and dependencies validated

* feat: enhance add-context with external context file management

- Add Stage 0: Detect external context files in .tmp/
- Offer options to extract, manage, or harvest external files
- Extract patterns from external context files for use in project intelligence
- Provide management options: update, remove, clean, or harvest
- Add examples showing external context extraction and management
- Update troubleshooting with external context file handling
- Integrate with /context harvest command for permanent context organization

* fix: comprehensive context system audit and restructuring

- Fix 6 command documentation inconsistencies in add-context.md
  * Correct /add-context vs /context harvest command references
  * Simplify Stage 0 workflow from 4 to 2 options
  * Update examples to match actual behavior
  * Remove non-existent operations from delegation section
  * Fix troubleshooting Q&A section

- Restructure registry.json with 4 major improvements
  * Replace 31 duplicate 'navigation' IDs with unique IDs per subfolder
    - core-navigation, development-navigation, openagents-repo-navigation, etc.
  * Add context:openagents-repo/* to developer and full profiles
    - Developers now have repo-specific guides and examples
  * Remove context:to-be-consumed/* from essential, developer, business, full
    - Keep only in advanced profile for system builders
  * Properly scope mastra-ai context via wildcard patterns

Validation Results:
- Registry: 220/220 paths valid, 0 missing dependencies
- Profiles: All appropriately scoped with no duplicate IDs
- Standards: MVI compliance, frontmatter, structure verified
- No regressions: All tests passing

Fixes issues with context organization, command consistency, and profile coverage.

* feat: add premium dark UI design system context

- Add comprehensive quick start guide for premium dark UI
- Add visual reference guide with ASCII diagrams
- Includes color palette, components, layouts, and best practices
- Provides glassmorphism and radial glow patterns
- Complete with accessibility guidelines and responsive design
- Ready-to-use code snippets and templates

* docs: update design navigation with premium dark UI guides

* fix: Clean up agent YAML frontmatter and add standards

Fixed YAML frontmatter issues in 18 agent files:
- Removed duplicate YAML keys (e.g., read: true followed by read: {})
- Removed orphaned list items without parent keys
- Fixed field names (permission: → permissions:)
- Removed extra --- delimiter blocks in content
- Cleaned up comments and invalid OpenCode fields

Changes:
- 14 subagent files fixed (core, code, development, system-builder)
- 4 primary/meta agent files fixed (openagent, opencoder, repo-manager, eval-runner)
- Net reduction: 439 lines removed, 116 lines added (cleaner YAML)

Added agent standards documentation:
- .opencode/context/openagents-repo/standards/agent-frontmatter.md
- .opencode/context/openagents-repo/standards/subagent-structure.md
- .opencode/context/openagents-repo/standards/navigation.md
- Updated main navigation.md with standards section

All files follow MVI principles (<200 lines) and document the 5 common
YAML mistakes that were fixed.

Fixes subagent recognition issues where agents were registered as 'all'
mode instead of 'subagent' mode due to malformed YAML.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

.opencode/agent/core/openagent.md

@@ -16,18 +16,18 @@ tools:
   bash: true
   task: true
   patch: true
-permission:
+permissions:
   bash:
-    "rm -rf *": ask
-    "rm -rf /*": deny
-    "sudo *": deny
-    "> /dev/*": deny
+    "rm -rf *": "ask"
+    "rm -rf /*": "deny"
+    "sudo *": "deny"
+    "> /dev/*": "deny"
   edit:
-    "**/*.env*": deny
-    "**/*.key": deny
-    "**/*.secret": deny
-    "node_modules/**": deny
-    ".git/**": deny
+    "**/*.env*": "deny"
+    "**/*.key": "deny"
+    "**/*.secret": "deny"
+    "node_modules/**": "deny"
+    ".git/**": "deny"
 ---
 Always use ContextScout for discovery of new tasks or context files.
 ContextScout is exempt from the approval gate rule. ContextScout is your secret weapon for quality, use it where possible.

.opencode/agent/core/opencoder.md

@@ -16,23 +16,23 @@ tools:
   glob: true
   bash: true
   patch: true
-permission:
+permissions:
   bash:
-    "rm -rf *": ask
-    "sudo *": deny
-    "chmod *": ask
-    "curl *": ask
-    "wget *": ask
-    "docker *": ask
-    "kubectl *": ask
+    "rm -rf *": "ask"
+    "sudo *": "deny"
+    "chmod *": "ask"
+    "curl *": "ask"
+    "wget *": "ask"
+    "docker *": "ask"
+    "kubectl *": "ask"
   edit:
-    "**/*.env*": deny
-    "**/*.key": deny
-    "**/*.secret": deny
-    "node_modules/**": deny
-    "**/__pycache__/**": deny
-    "**/*.pyc": deny
-    ".git/**": deny
+    "**/*.env*": "deny"
+    "**/*.key": "deny"
+    "**/*.secret": "deny"
+    "node_modules/**": "deny"
+    "**/__pycache__/**": "deny"
+    "**/*.pyc": "deny"
+    ".git/**": "deny"
 ---
 
 # Development Agent

.opencode/agent/eval-runner.md

@@ -1,194 +1,34 @@
 ---
 # OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
-name: OpenCoder
-description: "Multi-language implementation agent for modular and functional development"
-mode: primary
-temperature: 0.1
-tools:
-  task: true
-  read: true
-  edit: true
-  write: true
-  grep: true
-  glob: true
-  bash: true
-  patch: true
-  bash:
-    "rm -rf *": "ask"
-    "sudo *": "deny"
-    "chmod *": "ask"
-    "curl *": "ask"
-    "wget *": "ask"
-    "docker *": "ask"
-    "kubectl *": "ask"
-  edit:
-    "**/*.env*": "deny"
-    "**/*.key": "deny"
-    "**/*.secret": "deny"
-    "node_modules/**": "deny"
-    "**/__pycache__/**": "deny"
-    "**/*.pyc": "deny"
-    ".git/**": "deny"
-  - development
-  - coding
-  - implementation
+id: eval-runner
+name: Eval Runner
+description: "Test harness for evaluation framework - DO NOT USE DIRECTLY"
+category: testing
+type: utility
+version: 1.0.0
+author: opencode
+mode: subagent
+temperature: 0.2
 ---
 
-# Development Agent
-Always start with phrase "DIGGING IN..."
-
-<critical_context_requirement>
-PURPOSE: Context files contain project-specific coding standards that ensure consistency, 
-quality, and alignment with established patterns. Without loading context first, 
-you will create code that doesn't match the project's conventions.
-
-BEFORE any code implementation (write/edit), ALWAYS load required context files:
-- Code tasks → .opencode/context/core/standards/code-quality.md (MANDATORY)
-- Language-specific patterns if available
-
-WHY THIS MATTERS:
-- Code without standards/code-quality.md → Inconsistent patterns, wrong architecture
-- Skipping context = wasted effort + rework
-
-CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort
-</critical_context_requirement>
-
-<critical_rules priority="absolute" enforcement="strict">
-  <rule id="approval_gate" scope="all_execution">
-    Request approval before ANY implementation (write, edit, bash). Read/list/glob/grep or using ContextScout for discovery don't require approval.
-    ALWAYS use ContextScout for discovery before implementation, before doing your own discovery.
-  </rule>
-  
-  <rule id="stop_on_failure" scope="validation">
-    STOP on test fail/build errors - NEVER auto-fix without approval
-  </rule>
-  
-  <rule id="report_first" scope="error_handling">
-    On fail: REPORT error → PROPOSE fix → REQUEST APPROVAL → Then fix (never auto-fix)
-  </rule>
-  
-  <rule id="incremental_execution" scope="implementation">
-    Implement ONE step at a time, validate each step before proceeding
-  </rule>
-</critical_rules>
-
-## Available Subagents (invoke via task tool)
-
-- `ContextScout` - Discover context files BEFORE coding (saves time!)
-- `CoderAgent` - Simple implementations
-- `TestEngineer` - Testing after implementation
-- `DocWriter` - Documentation generation
-
-**Invocation syntax**:
-```javascript
-task(
-  subagent_type="ContextScout",
-  description="Brief description",
-  prompt="Detailed instructions for the subagent"
-)
-```
-
-Focus:
-You are a coding specialist focused on writing clean, maintainable, and scalable code. Your role is to implement applications following a strict plan-and-approve workflow using modular and functional programming principles.
-
-Adapt to the project's language based on the files you encounter (TypeScript, Python, Go, Rust, etc.).
-
-Core Responsibilities
-Implement applications with focus on:
-
-- Modular architecture design
-- Functional programming patterns where appropriate
-- Type-safe implementations (when language supports it)
-- Clean code principles
-- SOLID principles adherence
-- Scalable code structures
-- Proper separation of concerns
-
-Code Standards
-
-- Write modular, functional code following the language's conventions
-- Follow language-specific naming conventions
-- Add minimal, high-signal comments only
-- Avoid over-complication
-- Prefer declarative over imperative patterns
-- Use proper type systems when available
-
-<delegation_rules>
-  <delegate_when>
-    <condition id="simple_task" trigger="focused_implementation" action="delegate_to_coder_agent">
-      For simple, focused implementations to save time
-    </condition>
-  </delegate_when>
-  
-  <execute_directly_when>
-    <condition trigger="single_file_simple_change">1-3 files, straightforward implementation</condition>
-  </execute_directly_when>
-</delegation_rules>
+# Eval Runner - Test Harness
 
-<workflow>
-  <stage id="1" name="ContextDiscovery" required="true">
-    1. Use `ContextScout` to discover relevant project files.
-    2. MANDATORY: Read `.opencode/context/core/standards/code-quality.md`.
-    3. Read `.opencode/context/core/workflows/component-planning.md`.
-    
-    *Constraint: You cannot create a valid plan until you have read the standards.*
-  </stage>
+**⚠️ DO NOT USE THIS AGENT DIRECTLY ⚠️**
 
-  <stage id="2" name="MasterPlanning" required="true" enforce="@approval_gate">
-    1. Create a session directory: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
-    2. **Decompose** the request into functional Components (Auth, DB, UI, etc.).
-    3. Create `master-plan.md` following the `component-planning.md` standard.
-       - Define Architecture.
-       - List Components in dependency order.
-    4. Present `master-plan.md` for approval.
-  </stage>
+This agent is a test harness used by the OpenCode evaluation framework.
 
-  <stage id="3" name="ComponentExecutionLoop" when="approved" enforce="@incremental_execution">
-    *Repeat for each Component in Master Plan:*
-    
-    1. **Plan Component**:
-       - Create `component-{name}.md` with detailed Interface, Tests, and Tasks.
-       - Request approval for this specific component's design.
-       
-    2. **Execute Component**:
-       - Load tasks from `component-{name}.md` into `TodoWrite`.
-       - Execute loop: `TodoRead` -> Implement -> Validate -> `TodoWrite`.
-       - If complex, delegate to `CoderAgent` passing `component-{name}.md`.
-       
-    3. **Integrate**:
-       - Mark component complete in `master-plan.md`.
-       - Verify integration with previous components.
-  </stage>
+## Purpose
 
-  <stage id="4" name="ValidationAndHandoff" enforce="@stop_on_failure">
-    1. Verify all components in `master-plan.md` are complete.
-    2. Run full system integration tests.
-    3. Ask user to clean up `.tmp` files.
-    4. Suggest `DocWriter` or `TestEngineer`.
-  </stage>
-</workflow>
+This file is **dynamically replaced** during test runs:
+- Before tests: Replaced with target agent's prompt (e.g., openagent, opencoder)
+- During tests: Acts as the target agent
+- After tests: Restored to this default state
 
-<execution_philosophy>
-  Development specialist with strict quality gates and context awareness.
-  
-  **Approach**: Plan → Approve → Load Context → Execute Incrementally → Validate → Handoff
-  **Mindset**: Quality over speed, consistency over convenience
-  **Safety**: Context loading, approval gates, stop on failure, incremental execution
-</execution_philosophy>
+## Configuration
 
-<constraints enforcement="absolute">
-  These constraints override all other considerations:
-  
-  1. NEVER execute write/edit without loading required context first
-  2. NEVER skip approval gate - always request approval before implementation
-  3. NEVER auto-fix errors - always report first and request approval
-  4. NEVER implement entire plan at once - always incremental, one step at a time
-  5. ALWAYS validate after each step (type check, lint, test)
-  
-  If you find yourself violating these rules, STOP and correct course.
-</constraints>
+- **ID**: eval-runner
+- **Mode**: subagent (test harness only)
+- **Status**: Template - will be overwritten during test runs
 
+If you see this prompt during a test run, something went wrong with the test setup.
 

.opencode/agent/meta/repo-manager.md

@@ -28,11 +28,12 @@ tools:
     "**/*.secret": "deny"
     "node_modules/**": "deny"
     ".git/**": "deny"
-  - repository
-  - meta
-  - coordination
-  - openagents-repo
-  - lazy-loading
+permissions:
+  bash:
+    "rm -rf *": "ask"
+    "rm -rf /*": "deny"
+    "sudo *": "deny"
+    "> /dev/*": "deny"
 ---
 
 <!-- ═══════════════════════════════════════════════════════════════════════════ -->

.opencode/agent/subagents/code/build-agent.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: BuildAgent
-description: "Type check and build validation agent"
+description: Type check and build validation agent
 mode: subagent
 temperature: 0.1
 tools:
@@ -13,6 +9,9 @@ tools:
   grep: true
   glob: true
   task: true
+  edit: false
+  write: false
+permissions:
   bash:
     "tsc": "allow"
     "mypy": "allow"
@@ -31,20 +30,12 @@ tools:
   task:
     contextscout: "allow"
     "*": "deny"
-  - build
-  - validation
-  - type-check
 ---
 
 # BuildAgent
 
 > **Mission**: Validate type correctness and build success — always grounded in project build standards discovered via ContextScout.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE running build checks. Load build standards, type-checking requirements, and project conventions first. This ensures you run the right commands for this project.
   </rule>

.opencode/agent/subagents/code/coder-agent.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: CoderAgent
-description: "Executes coding subtasks in sequence, ensuring completion as specified"
+description: Executes coding subtasks in sequence, ensuring completion as specified
 mode: subagent
 temperature: 0
 tools:
@@ -16,6 +12,7 @@ tools:
   bash: false
   patch: true
   task: true
+permissions:
   bash:
     "*": "deny"
   edit:
@@ -28,19 +25,12 @@ tools:
     contextscout: "allow"
     externalscout: "allow"
     "*": "deny"
-  - coding
-  - implementation
 ---
 
 # CoderAgent
 
 > **Mission**: Execute coding subtasks precisely, one at a time, with full context awareness and self-review before handoff.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE writing any code. Load project standards, naming conventions, and security patterns first. This is not optional — it's how you produce code that fits the project.
   </rule>

.opencode/agent/subagents/code/reviewer.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: CodeReviewer
-description: "Code review, security, and quality assurance agent"
+description: Code review, security, and quality assurance agent
 mode: subagent
 temperature: 0.1
 tools:
@@ -15,6 +11,7 @@ tools:
   edit: false
   write: false
   task: true
+permissions:
   bash:
     "*": "deny"
   edit:
@@ -24,20 +21,12 @@ tools:
   task:
     contextscout: "allow"
     "*": "deny"
-  - review
-  - quality
-  - security
 ---
 
 # CodeReviewer
 
 > **Mission**: Perform thorough code reviews for correctness, security, and quality — always grounded in project standards discovered via ContextScout.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE reviewing any code. Load code quality standards, security patterns, and naming conventions first. Reviewing without standards = meaningless feedback.
   </rule>

.opencode/agent/subagents/code/tester.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: TestEngineer
-description: "Test authoring and TDD agent"
+description: Test authoring and TDD agent
 mode: subagent
 temperature: 0.1
 tools:
@@ -15,6 +11,7 @@ tools:
   write: true
   bash: true
   task: true
+permissions:
   bash:
     "npx vitest *": "allow"
     "npx jest *": "allow"
@@ -36,19 +33,12 @@ tools:
   task:
     contextscout: "allow"
     "*": "deny"
-  - testing
-  - tdd
 ---
 
 # TestEngineer
 
 > **Mission**: Author comprehensive tests following TDD principles — always grounded in project testing standards discovered via ContextScout.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE writing any tests. Load testing standards, coverage requirements, and TDD patterns first. Tests without standards = tests that don't match project conventions.
   </rule>

.opencode/agent/subagents/core/context-manager.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: ContextManager
-description: "Context organization and lifecycle management specialist - discovers, catalogs, validates, and maintains project context structure with dependency tracking"
+description: Context organization and lifecycle management specialist - discovers, catalogs, validates, and maintains project context structure with dependency tracking
 mode: subagent
 temperature: 0.1
 tools:
@@ -15,6 +11,7 @@ tools:
   write: true
   bash: true
   task: true
+permissions:
   read:
     "**/*": "allow"
   grep:
@@ -41,22 +38,12 @@ tools:
   task:
     "contextscout": "allow"
     "*": "deny"
-  - context
-  - organization
-  - management
-  - lifecycle
-  - catalog
 ---
 
 # ContextManager
 
 > **Mission**: Discover, catalog, validate, and maintain project context structure with dependency tracking and lifecycle management.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_root">
     The ONLY entry point is `.opencode/context/`. All operations start from navigation.md files. Never hardcode paths — follow navigation dynamically.
   </rule>

.opencode/agent/subagents/core/context-retriever.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: Context Retriever
-description: "Generic context search and retrieval specialist for finding relevant context files, standards, and guides in any repository"
+description: Generic context search and retrieval specialist for finding relevant context files, standards, and guides in any repository
 mode: subagent
 temperature: 0.1
 tools:
@@ -15,18 +11,13 @@ tools:
   bash: false
   edit: false
   write: false
+permissions:
   bash:
     "*": "deny"
   edit:
     "**/*": "deny"
   write:
     "**/*": "deny"
-  context: []
-  tools: []
-  - context
-  - search
-  - retrieval
-  - subagent
 ---
 
 # Context Retriever Agent

.opencode/agent/subagents/core/contextscout.md

@@ -1,61 +1,21 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: ContextScout
-description: "Discovers and recommends context files from .opencode/context/ ranked by priority. Suggests ExternalScout when a framework/library is mentioned but not found internally."
+description: Discovers and recommends context files from .opencode/context/ ranked by priority. Suggests ExternalScout when a framework/library is mentioned but not found internally.
 mode: subagent
-temperature: 0.1
 tools:
   read: true
   grep: true
   glob: true
-  read:
-    "**/*": "allow"
-  grep:
-    "**/*": "allow"
-  glob:
-    "**/*": "allow"
-  bash:
-    "*": "deny"
-  edit:
-    "**/*": "deny"
-  write:
-    "**/*": "deny"
-  task:
-    "*": "deny"
-  skill:
-    "*": "deny"
-  lsp:
-    "*": "deny"
-  todoread:
-    "*": "deny"
-  todowrite:
-    "*": "deny"
-  webfetch:
-    "*": "deny"
-  websearch:
-    "*": "deny"
-  codesearch:
-    "*": "deny"
-  external_directory:
-    "*": "deny"
-  - context
-  - search
-  - discovery
-  - subagent
+  write: false
+  edit: false
+  bash: false
+  task: false
 ---
 
 # ContextScout
 
 > **Mission**: Discover and recommend context files from `.opencode/context/` (or custom_dir from paths.json) ranked by priority. Suggest ExternalScout when a framework/library has no internal coverage.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_root">
     The context root is determined by paths.json (loaded via @ reference). Default is `.opencode/context/`. If custom_dir is set in paths.json, use that instead. Start by reading `{context_root}/navigation.md`. Never hardcode paths to specific domains — follow navigation dynamically.
   </rule>
@@ -85,7 +45,6 @@ tools:
     - Flag frameworks/libraries for ExternalScout when needed
   </tier>
   <conflict_resolution>Tier 1 always overrides Tier 2/3. If returning more files conflicts with verify-before-recommend → verify first. If a path seems relevant but isn't confirmed → don't include it.</conflict_resolution>
----
 
 ## How It Works
 
@@ -95,13 +54,6 @@ tools:
 2. **Follow navigation** — Read `navigation.md` files from `.opencode/context/` downward. They are the map.
 3. **Return ranked files** — Priority order: Critical → High → Medium. Brief summary per file.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
----
-
 ## Response Format
 
 ```markdown
@@ -133,13 +85,6 @@ The framework **[Name]** has no internal context coverage.
 → Invoke ExternalScout to fetch live docs: `Use ExternalScout for [Name]: [user's question]`
 ```
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
----
-
 ## What NOT to Do
 
 - ❌ Don't hardcode domain→path mappings — follow navigation dynamically

.opencode/agent/subagents/core/documentation.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: DocWriter
-description: "Documentation authoring agent"
+description: Documentation authoring agent
 mode: subagent
 temperature: 0.2
 tools:
@@ -15,6 +11,7 @@ tools:
   write: true
   bash: false
   task: true
+permissions:
   bash:
     "*": "deny"
   edit:
@@ -26,19 +23,12 @@ tools:
   task:
     contextscout: "allow"
     "*": "deny"
-  - documentation
-  - docs
 ---
 
 # DocWriter
 
 > **Mission**: Create and update documentation that is concise, example-driven, and consistent with project conventions — always grounded in doc standards discovered via ContextScout.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE writing any documentation. Load documentation standards, formatting conventions, and tone guidelines first. Docs without standards = inconsistent documentation.
   </rule>

.opencode/agent/subagents/core/externalscout.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: ExternalScout
-description: "Fetches live, version-specific documentation for external libraries and frameworks using Context7 and other sources. Filters, sorts, and returns relevant documentation."
+description: Fetches live, version-specific documentation for external libraries and frameworks using Context7 and other sources. Filters, sorts, and returns relevant documentation.
 mode: subagent
 temperature: 0.1
 tools:
@@ -13,6 +9,13 @@ tools:
   skill: true
   grep: true
   webfetch: true
+  write: true
+  edit: true
+  glob: true
+  task: false
+  todoread: false
+  todowrite: false
+permissions:
   read:
     ".opencode/skill/context7/**": "allow"
     ".tmp/external-context/**": "allow"
@@ -49,11 +52,6 @@ tools:
     "*": "deny"
   todowrite:
     "*": "deny"
-  - external-docs
-  - libraries
-  - frameworks
-  - context7
-  - subagent
 ---
 
 # ExternalScout

.opencode/agent/subagents/core/task-manager.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: TaskManager
-description: "JSON-driven task breakdown specialist transforming complex features into atomic, verifiable subtasks with dependency tracking and CLI integration"
+description: JSON-driven task breakdown specialist transforming complex features into atomic, verifiable subtasks with dependency tracking and CLI integration
 mode: subagent
 temperature: 0.1
 tools:
@@ -16,6 +12,7 @@ tools:
   bash: true
   task: true
   patch: true
+permissions:
   bash:
     "npx ts-node*task-cli*": "allow"
     "mkdir -p .tmp/tasks*": "allow"
@@ -27,12 +24,8 @@ tools:
     "**/*.secret": "deny"
     "node_modules/**": "deny"
     ".git/**": "deny"
-  skills:
-    - task-management  # CLI for status, validation, and completion tracking
-  - planning
-  - tasks
-  - breakdown
-  - json
+skills:
+  - task-management
 ---
 
 <context>

.opencode/agent/subagents/development/devops-specialist.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: OpenDevopsSpecialist
-description: "DevOps specialist subagent - CI/CD, infrastructure as code, deployment automation"
+description: DevOps specialist subagent - CI/CD, infrastructure as code, deployment automation
 mode: subagent
 temperature: 0.1
 tools:
@@ -15,6 +11,7 @@ tools:
   task: true
   grep: true
   glob: true
+permissions:
   task:
     contextscout: "allow"
     "*": "deny"
@@ -39,23 +36,12 @@ tools:
     "**/*.env*": "deny"
     "**/*.key": "deny"
     "**/*.secret": "deny"
-  - devops
-  - ci-cd
-  - infrastructure
-  - deployment
-  - docker
-  - kubernetes
 ---
 
 # DevOps Specialist Subagent
 
 > **Mission**: Design and implement CI/CD pipelines, infrastructure automation, and cloud deployments — always grounded in project standards and security best practices.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE any infrastructure or pipeline work. Load deployment patterns, security standards, and CI/CD conventions first. This is not optional.
   </rule>

.opencode/agent/subagents/development/frontend-specialist.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: OpenFrontendSpecialist
-description: "Frontend UI design specialist - subagent for design systems, themes, animations"
+description: Frontend UI design specialist - subagent for design systems, themes, animations
 mode: subagent
 temperature: 0.2
 tools:
@@ -15,6 +11,7 @@ tools:
   task: true
   glob: true
   grep: true
+permissions:
   task:
     contextscout: "allow"
     externalscout: "allow"
@@ -38,12 +35,7 @@ tools:
 
 # Frontend Design Subagent
 
-> **Mission**: Create complete UI designs with cohesive design systems, themes, and animations — always grounded in current library docs and project standards.
-
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
+> **Mission**: Create complete UI designs with cohesive design systems, themes, animations — always grounded in current library docs and project standards.
 
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE any design or implementation work. Load design system standards, UI conventions, and accessibility requirements first.

.opencode/agent/subagents/system-builder/context-organizer.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: ContextOrganizer
-description: "Organizes and generates context files (domain, processes, standards, templates) for optimal knowledge management"
+description: Organizes and generates context files (domain, processes, standards, templates) for optimal knowledge management
 mode: subagent
 temperature: 0.1
 tools:
@@ -14,6 +10,7 @@ tools:
   grep: true
   glob: true
   task: true
+permissions:
   task:
     contextscout: "allow"
     "*": "deny"
@@ -21,20 +18,12 @@ tools:
     "**/*.env*": "deny"
     "**/*.key": "deny"
     "**/*.secret": "deny"
-  - context:core/context-system/*
-  - context
-  - organization
 ---
 
 # Context Organizer
 
 > **Mission**: Generate well-organized, MVI-compliant context files that provide domain knowledge, process documentation, quality standards, and reusable templates.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE generating any context files. You need to understand the existing context system structure, MVI standards, and frontmatter requirements before creating anything new.
   </rule>

.opencode/agent/subagents/system-builder/workflow-designer.md

@@ -1,10 +1,6 @@
 ---
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
 name: WorkflowDesigner
-description: "Designs complete workflow definitions with context dependencies and success criteria"
+description: Designs complete workflow definitions with context dependencies and success criteria
 mode: subagent
 temperature: 0.1
 tools:
@@ -14,6 +10,7 @@ tools:
   grep: true
   glob: true
   task: true
+permissions:
   task:
     contextscout: "allow"
     "*": "deny"
@@ -21,19 +18,12 @@ tools:
     "**/*.env*": "deny"
     "**/*.key": "deny"
     "**/*.secret": "deny"
-  - workflow
-  - design
 ---
 
 # Workflow Designer
 
 > **Mission**: Design complete, executable workflow definitions that map use cases to agent coordination patterns — always grounded in existing workflow standards discovered via ContextScout.
 
----
-# OpenCode Agent Configuration
-# Metadata (id, name, category, type, version, author, tags, dependencies) is stored in:
-# .opencode/config/agent-metadata.json
-
   <rule id="context_first">
     ALWAYS call ContextScout BEFORE designing any workflow. You need to understand existing workflow patterns, agent capabilities, and coordination standards before creating new workflows.
   </rule>

.opencode/context/openagents-repo/navigation.md

@@ -2,7 +2,7 @@
 
 **Purpose**: Context files specific to the OpenAgents Control repository
 
-**Last Updated**: 2026-01-30
+**Last Updated**: 2026-01-31
 
 ---
 
@@ -10,6 +10,7 @@
 
 | Function | Files | Purpose |
 |----------|-------|---------|
+| **Standards** | 2 files | Agent creation standards |
 | **Concepts** | 2 files | Core ideas and principles |
 | **Examples** | 1 file | Working code samples |
 | **Guides** | 10 files | Step-by-step workflows |
@@ -18,6 +19,17 @@
 
 ---
 
+## Standards (Agent Creation)
+
+| File | Topic | Priority |
+|------|-------|----------|
+| `standards/agent-frontmatter.md` | Valid OpenCode YAML frontmatter | ⭐⭐⭐⭐⭐ |
+| `standards/subagent-structure.md` | Standard subagent file structure | ⭐⭐⭐⭐⭐ |
+
+**When to read**: Before creating or modifying any agent files
+
+---
+
 ## Concepts (Core Ideas)
 
 | File | Topic | Priority |
@@ -101,11 +113,13 @@
 4. If errors: Load `errors/tool-permission-errors.md`
 
 ### For Agent Creation:
-1. Load `core-concepts/agents.md` (understand structure)
-2. Load `guides/adding-agent.md` (step-by-step)
-3. **If using external libraries**: Load `guides/external-libraries-workflow.md` (fetch docs)
-4. Load `examples/subagent-prompt-structure.md` (if subagent)
-5. Load `guides/testing-agent.md` (validate)
+1. Load `standards/agent-frontmatter.md` (valid YAML frontmatter)
+2. Load `standards/subagent-structure.md` (file structure)
+3. Load `core-concepts/agents.md` (understand system)
+4. Load `guides/adding-agent.md` (step-by-step)
+5. **If using external libraries**: Load `guides/external-libraries-workflow.md` (fetch docs)
+6. Load `examples/subagent-prompt-structure.md` (if subagent)
+7. Load `guides/testing-agent.md` (validate)
 
 ### For Issue Management:
 1. Load `guides/github-issues-workflow.md` (understand workflow)
@@ -124,6 +138,7 @@
 
 All files follow MVI principle (<200 lines):
 
+- ✅ Standards: <200 lines
 - ✅ Concepts: <100 lines
 - ✅ Examples: <100 lines
 - ✅ Guides: <150 lines

.opencode/context/openagents-repo/standards/agent-frontmatter.md

@@ -0,0 +1,194 @@
+<!-- Context: openagents-repo/standards/agent-frontmatter | Priority: critical | Version: 1.0 | Updated: 2026-01-31 -->
+# Standard: Agent YAML Frontmatter
+
+**Purpose**: Valid OpenCode agent frontmatter structure and common mistakes to avoid  
+**Priority**: CRITICAL - Load this before creating or modifying agent files
+
+---
+
+## Core Principle
+
+Agent frontmatter must contain ONLY valid OpenCode fields. All other metadata (id, name, category, tags, dependencies) belongs in `.opencode/config/agent-metadata.json`.
+
+**Why**: OpenCode validates frontmatter strictly. Extra fields cause validation errors.
+
+---
+
+## Valid OpenCode Fields
+
+### Required
+```yaml
+---
+name: AgentName                      # Display name
+description: "What this agent does"  # When to use
+mode: subagent                       # primary, subagent, or all
+---
+```
+
+### Optional
+```yaml
+temperature: 0.1                     # Response randomness (0.0-1.0)
+model: anthropic/claude-sonnet-4     # Model override
+maxSteps: 50                         # Max iterations
+disable: false                       # Disable agent
+hidden: false                        # Hide from autocomplete
+prompt: "{file:./prompts/custom.txt}" # Custom prompt
+
+tools:                               # Tool access
+  read: true
+  write: false
+  edit: false
+  bash: false
+  task: false
+
+permissions:                         # Permission rules
+  bash:
+    "git *": "allow"
+    "*": "deny"
+  edit:
+    "**/*.env*": "deny"
+  task:
+    contextscout: "allow"
+    "*": "deny"
+
+skills:                              # Skills to load
+  - task-management
+```
+
+---
+
+## Complete Example
+
+```yaml
+---
+name: TestEngineer
+description: Test authoring and TDD agent
+mode: subagent
+temperature: 0.1
+tools:
+  read: true
+  grep: true
+  edit: true
+  write: true
+  bash: true
+  task: true
+permissions:
+  bash:
+    "npx vitest *": "allow"
+    "pytest *": "allow"
+    "sudo *": "deny"
+    "*": "deny"
+  edit:
+    "**/*.env*": "deny"
+  task:
+    contextscout: "allow"
+    "*": "deny"
+---
+```
+
+---
+
+## Common Mistakes (Fixed in 18 Agents)
+
+### 1. Duplicate Keys ❌
+```yaml
+tools:
+  read: true
+  read: {"**/*": "allow"}  # ❌ Duplicate key
+```
+**Fix**: Use only one declaration per key
+
+### 2. Orphaned List Items ❌
+```yaml
+tools:
+  read: true
+  - write: false  # ❌ No parent key
+```
+**Fix**: Proper YAML structure (no orphaned items)
+
+### 3. Wrong Field Names ❌
+```yaml
+permission:  # ❌ Should be 'permissions'
+  bash:
+    "*": "deny"
+```
+**Fix**: Use correct field name `permissions:`
+
+### 4. Extra Delimiter Blocks ❌
+```yaml
+---
+name: MyAgent
+---
+# Content
+---  # ❌ Extra delimiter
+More content
+```
+**Fix**: Only one `---` block at top
+
+### 5. Invalid OpenCode Fields ❌
+```yaml
+---
+id: my-agent          # ❌ Not valid
+category: development # ❌ Not valid
+type: agent           # ❌ Not valid
+version: 1.0.0        # ❌ Not valid
+tags: [coding]        # ❌ Not valid
+dependencies: []      # ❌ Not valid
+```
+**Fix**: Move to `.opencode/config/agent-metadata.json`:
+```json
+{
+  "agents": {
+    "my-agent": {
+      "id": "my-agent",
+      "category": "development",
+      "type": "agent",
+      "version": "1.0.0",
+      "tags": ["coding"],
+      "dependencies": []
+    }
+  }
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Only valid OpenCode fields?
+- [ ] No duplicate keys?
+- [ ] No orphaned list items?
+- [ ] Correct field names (`permissions` not `permission`)?
+- [ ] Only one `---` delimiter at top?
+- [ ] Metadata moved to agent-metadata.json?
+- [ ] Valid YAML syntax?
+
+---
+
+## Validation Commands
+
+```bash
+# Check YAML syntax
+yq eval '.opencode/agent/category/agent.md' > /dev/null
+
+# Find duplicate keys
+grep -A 50 "^---$" agent.md | grep -E "^[a-z_]+:" | sort | uniq -d
+
+# List all frontmatter keys
+grep -A 50 "^---$" agent.md | grep -E "^[a-z_]+:" | cut -d: -f1
+```
+
+**Valid keys**: `name`, `description`, `mode`, `temperature`, `model`, `maxSteps`, `disable`, `hidden`, `prompt`, `tools`, `permissions`, `skills`
+
+---
+
+## Related
+
+- **Agent Metadata**: `core-concepts/agent-metadata.md`
+- **Subagent Structure**: `standards/subagent-structure.md`
+- **Adding Agents**: `guides/adding-agent.md`
+- **OpenCode Docs**: https://opencode.ai/docs/agents/
+
+---
+
+**Last Updated**: 2026-01-31 | **Version**: 1.0.0

.opencode/context/openagents-repo/standards/navigation.md

@@ -0,0 +1,159 @@
+<!-- Context: openagents-repo/standards/navigation | Priority: critical | Version: 1.0 | Updated: 2026-01-31 -->
+# OpenAgents Repo Standards
+
+**Purpose**: Standards for creating and maintaining agents in OpenAgents Control  
+**Last Updated**: 2026-01-31
+
+---
+
+## Overview
+
+This directory contains standards for agent creation, focusing on:
+- Valid OpenCode YAML frontmatter structure
+- Subagent file organization and patterns
+- Common mistakes and how to avoid them
+
+These standards emerged from fixing YAML frontmatter issues across 18 agent files.
+
+---
+
+## Standards Files
+
+| File | Description | Priority | Lines |
+|------|-------------|----------|-------|
+| [agent-frontmatter.md](agent-frontmatter.md) | Valid OpenCode frontmatter fields and common mistakes | critical | <200 |
+| [subagent-structure.md](subagent-structure.md) | Standard structure for subagent files | critical | <200 |
+
+---
+
+## Quick Reference
+
+### Valid OpenCode Fields (Frontmatter)
+
+**Required**:
+- `name` - Display name
+- `description` - When to use this agent
+- `mode` - Agent type (primary, subagent, all)
+
+**Optional**:
+- `temperature` - Response randomness (0.0-1.0)
+- `model` - Model override
+- `maxSteps` - Max iterations
+- `disable` - Disable agent
+- `hidden` - Hide from autocomplete
+- `prompt` - Custom prompt file
+- `tools` - Tool access config
+- `permissions` - Permission rules
+- `skills` - Skills to load
+
+### Invalid Fields (Move to agent-metadata.json)
+
+These fields are NOT valid in OpenCode frontmatter:
+- `id` - Agent identifier
+- `category` - Agent category
+- `type` - Component type
+- `version` - Version number
+- `author` - Author identifier
+- `tags` - Discovery tags
+- `dependencies` - Component dependencies
+
+**Solution**: Move these to `.opencode/config/agent-metadata.json`
+
+---
+
+## Common Mistakes Fixed
+
+### 1. Duplicate YAML Keys
+**Problem**: `read: true` followed by `read: {"**/*": "allow"}`  
+**Fix**: Use only one declaration per key
+
+### 2. Orphaned List Items
+**Problem**: Lines without parent keys (e.g., `- write: false`)  
+**Fix**: Proper YAML structure with parent keys
+
+### 3. Wrong Field Names
+**Problem**: `permission:` instead of `permissions:`  
+**Fix**: Use correct field name `permissions:`
+
+### 4. Extra Delimiter Blocks
+**Problem**: Multiple `---` blocks in content  
+**Fix**: Only one frontmatter block at top
+
+### 5. Invalid OpenCode Fields
+**Problem**: Fields like `id`, `category`, `type` in frontmatter  
+**Fix**: Move to agent-metadata.json
+
+---
+
+## Loading Strategy
+
+### For Creating New Agents
+1. Load `agent-frontmatter.md` - Understand valid fields
+2. Load `subagent-structure.md` - Follow structure pattern
+3. Reference existing agents as examples
+4. Validate YAML syntax before committing
+
+### For Fixing Existing Agents
+1. Load `agent-frontmatter.md` - Identify invalid fields
+2. Check for common mistakes (duplicates, orphans, wrong names)
+3. Move invalid fields to agent-metadata.json
+4. Validate with YAML parser
+
+### For Code Reviews
+1. Load `agent-frontmatter.md` - Check frontmatter validity
+2. Load `subagent-structure.md` - Verify structure compliance
+3. Check for common mistakes
+4. Validate YAML syntax
+
+---
+
+## Validation Commands
+
+### Check YAML Syntax
+```bash
+yq eval '.opencode/agent/category/agent.md' > /dev/null
+```
+
+### Check for Duplicate Keys
+```bash
+grep -A 50 "^---$" .opencode/agent/category/agent.md | grep -E "^[a-z_]+:" | sort | uniq -d
+```
+
+### List All Frontmatter Keys
+```bash
+grep -A 50 "^---$" .opencode/agent/category/agent.md | grep -E "^[a-z_]+:" | cut -d: -f1
+```
+
+Valid keys: `name`, `description`, `mode`, `temperature`, `model`, `maxSteps`, `disable`, `hidden`, `prompt`, `tools`, `permissions`, `skills`
+
+---
+
+## Related Context
+
+### Core Concepts
+- [Agent Metadata System](../core-concepts/agent-metadata.md) - Centralized metadata management
+- [Agents](../core-concepts/AGENTS.md) - Agent system overview
+- [Categories](../core-concepts/categories.md) - Agent categorization
+
+### Guides
+- [Adding Agents](../guides/adding-agent.md) - How to create new agents
+- [Testing Agents](../guides/testing-agent.md) - Agent testing workflow
+
+### Lookup
+- [File Locations](../lookup/file-locations.md) - Where files go
+
+---
+
+## History
+
+**2026-01-31**: Initial standards created after fixing YAML frontmatter issues in 18 agent files. Issues fixed:
+- Duplicate YAML keys (e.g., `read: true` + `read: {"**/*": "allow"}`)
+- Orphaned list items (lines without parent keys)
+- Wrong field names (`permission:` → `permissions:`)
+- Extra `---` delimiter blocks in content
+- Invalid OpenCode fields in frontmatter
+
+---
+
+**Version**: 1.0.0  
+**Maintainer**: OpenAgents Control Team

.opencode/context/openagents-repo/standards/subagent-structure.md

@@ -0,0 +1,192 @@
+<!-- Context: openagents-repo/standards/subagent-structure | Priority: critical | Version: 1.0 | Updated: 2026-01-31 -->
+# Standard: Subagent File Structure
+
+**Purpose**: Standard structure for subagent files  
+**Priority**: CRITICAL - Load this before creating subagent files
+
+---
+
+## File Template
+
+```markdown
+---
+name: AgentName
+description: Brief description
+mode: subagent
+temperature: 0.1
+tools: {...}
+permissions: {...}
+---
+
+# AgentName
+> **Mission**: One-sentence mission
+
+<rule id="rule_name">Rule description</rule>
+
+<context>
+  <system>Role in pipeline</system>
+  <domain>Expertise area</domain>
+  <task>What agent does</task>
+  <constraints>Limitations</constraints>
+</context>
+
+<tier level="1" desc="Critical">
+  - @rule_id: Description
+</tier>
+
+## Workflow
+### Step 1: Preparation
+### Step 2: Execution
+### Step 3: Output
+
+## Output Format
+```yaml
+status: "success" | "failure"
+```
+```
+
+---
+
+## Section Details
+
+### 1. Frontmatter
+- ONLY valid OpenCode fields (see agent-frontmatter.md)
+- No duplicate keys, orphaned items, or invalid fields
+
+### 2. Header + Mission
+```markdown
+# TestEngineer
+> **Mission**: Author tests following TDD — grounded in project standards.
+```
+
+### 3. Critical Rules (3-5 max)
+```markdown
+<rule id="context_first">ALWAYS call ContextScout BEFORE writing tests.</rule>
+<rule id="positive_and_negative">EVERY behavior needs positive AND negative tests.</rule>
+```
+
+### 4. Context
+```markdown
+<context>
+  <system>Code quality gate</system>
+  <domain>Code review, security, quality</domain>
+  <task>Review code against standards</task>
+  <constraints>Read-only, no modifications</constraints>
+</context>
+```
+
+### 5. Execution Tiers
+```markdown
+<tier level="1" desc="Critical">
+  - @context_first: Load context first
+</tier>
+<tier level="2" desc="Core">
+  - Load standards
+  - Analyze code
+</tier>
+<conflict_resolution>Tier 1 overrides Tier 2/3</conflict_resolution>
+```
+
+---
+
+## Tool Permission Patterns
+
+### Read-Only (Reviewers, Analyzers)
+```yaml
+tools: {read: true, grep: true, glob: true, bash: false, edit: false, write: false}
+permissions:
+  bash: {"*": "deny"}
+  edit: {"**/*": "deny"}
+  task: {contextscout: "allow", "*": "deny"}
+```
+
+### Write-Enabled (Coders, Testers)
+```yaml
+tools: {read: true, edit: true, write: true, bash: true}
+permissions:
+  bash: {"npm test *": "allow", "git *": "allow", "sudo *": "deny", "*": "deny"}
+  edit: {"**/*.env*": "deny", "**/*.key": "deny"}
+  task: {contextscout: "allow", "*": "deny"}
+```
+
+### Restricted Bash (Task Managers)
+```yaml
+tools: {read: true, bash: true}
+permissions:
+  bash: {"npx ts-node*task-cli*": "allow", "mkdir -p .tmp/tasks*": "allow", "*": "deny"}
+```
+
+---
+
+## File Organization
+
+```
+.opencode/agent/subagents/
+├── code/           # tester, reviewer, coder-agent, build-agent
+├── core/           # task-manager, contextscout, documentation
+├── system-builder/ # agent-generator, command-creator
+└── utils/          # image-specialist
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Valid OpenCode frontmatter (no extra fields)?
+- [ ] Mission statement present?
+- [ ] 3-5 critical rules with unique IDs?
+- [ ] Context section complete?
+- [ ] Execution tiers defined with conflict resolution?
+- [ ] Workflow steps clear and actionable?
+- [ ] Output format specified?
+- [ ] Tool permissions appropriate for role?
+- [ ] File in correct category directory?
+- [ ] No YAML syntax errors?
+
+---
+
+## Common Patterns
+
+**Context-First Pattern**:
+```markdown
+<rule id="context_first">
+  ALWAYS call ContextScout BEFORE starting work. Load relevant standards first.
+</rule>
+```
+
+**Read-Only Pattern**:
+```markdown
+<rule id="read_only">
+  Read-only agent. NEVER use write, edit, or bash. Provide suggestions only.
+</rule>
+```
+
+**Security Pattern**:
+```markdown
+permissions:
+  edit:
+    "**/*.env*": "deny"
+    "**/*.key": "deny"
+    "**/*.secret": "deny"
+```
+
+---
+
+## Examples
+
+**See existing subagents**:
+- `.opencode/agent/subagents/code/tester.md` - Write-enabled with tests
+- `.opencode/agent/subagents/code/reviewer.md` - Read-only reviewer
+- `.opencode/agent/subagents/core/task-manager.md` - Restricted bash
+
+---
+
+## Related
+
+- **Frontmatter**: `standards/agent-frontmatter.md`
+- **Metadata**: `core-concepts/agent-metadata.md`
+- **Adding Agents**: `guides/adding-agent.md`
+
+---
+
+**Last Updated**: 2026-01-31 | **Version**: 1.0.0

.opencode/context/ui/web/design/guides/premium-dark-ui-quick-start.md

@@ -0,0 +1,638 @@
+# Premium Dark UI - Quick Start Guide
+
+**Goal**: Create a sophisticated, modern dark website with glassmorphism and depth.
+
+**Time to implement**: 30-60 minutes
+
+---
+
+## 1. COLOR PALETTE (Copy This)
+
+```css
+/* Backgrounds */
+--bg-deep-dark: #0a0f0d;      /* Main background */
+--bg-black: #000000;           /* Alternate sections */
+
+/* Text */
+--text-heading: #ffffff;       /* Headings */
+--text-body: #cbd5e1;          /* Body (slate-300) */
+--text-muted: #94a3b8;         /* Muted (slate-400) */
+
+/* Accent */
+--accent: #80cca5;             /* Green - CTAs, links, highlights */
+--accent-hover: #6bb890;       /* Hover state */
+
+/* Glass */
+--glass-bg: rgba(255, 255, 255, 0.02);
+--glass-border: rgba(255, 255, 255, 0.1);
+```
+
+**Rule**: Use ONLY these colors. No exceptions.
+
+---
+
+## 2. CORE COMPONENTS (4 Building Blocks)
+
+### A. Section Wrapper
+
+```tsx
+// PremiumSection.tsx
+export function PremiumSection({ children, withGlow = true }) {
+  return (
+    <section className="relative py-24 px-4 bg-[#0a0f0d] overflow-hidden">
+      {withGlow && (
+        <div 
+          className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[600px] h-[600px] pointer-events-none"
+          style={{
+            background: 'radial-gradient(circle, rgba(128, 204, 165, 0.15) 0%, transparent 70%)',
+            opacity: 0.15
+          }}
+        />
+      )}
+      <div className="max-w-7xl mx-auto relative z-10">
+        {children}
+      </div>
+    </section>
+  )
+}
+```
+
+### B. Glass Card
+
+```tsx
+// PremiumCard.tsx
+export function PremiumCard({ children, className = "" }) {
+  return (
+    <div className={`
+      p-8 rounded-2xl 
+      bg-white/[0.02] 
+      border border-white/10 
+      backdrop-blur-xl 
+      shadow-2xl 
+      transition-all duration-300
+      hover:bg-white/[0.04] 
+      hover:border-[#80cca5]/30
+      ${className}
+    `}>
+      {children}
+    </div>
+  )
+}
+```
+
+### C. Heading
+
+```tsx
+// PremiumHeading.tsx
+export function PremiumHeading({ children, accent, as: Tag = 'h2' }) {
+  return (
+    <Tag className="text-3xl md:text-5xl font-bold text-white mb-6">
+      {children}
+      {accent && <span className="text-[#80cca5]"> {accent}</span>}
+    </Tag>
+  )
+}
+```
+
+### D. Radial Glow
+
+```tsx
+// RadialGlow.tsx
+export function RadialGlow({ className = "" }) {
+  return (
+    <div 
+      className={`absolute -translate-x-1/2 -translate-y-1/2 w-[600px] h-[600px] pointer-events-none ${className}`}
+      style={{
+        background: 'radial-gradient(circle, rgba(128, 204, 165, 0.15) 0%, transparent 70%)',
+        opacity: 0.15
+      }}
+    />
+  )
+}
+```
+
+---
+
+## 3. SPACING SYSTEM
+
+```css
+/* Use these values ONLY */
+py-4   /* 16px - Small spacing */
+py-8   /* 32px - Medium spacing */
+py-12  /* 48px - Large spacing */
+py-24  /* 96px - Section spacing */
+
+px-4   /* 16px - Mobile padding */
+px-8   /* 32px - Card padding */
+px-12  /* 48px - Large card padding */
+
+gap-4  /* 16px - Small gaps */
+gap-8  /* 32px - Medium gaps */
+gap-12 /* 48px - Large gaps */
+
+mb-4   /* 16px - Small margin bottom */
+mb-6   /* 24px - Medium margin bottom */
+mb-8   /* 32px - Large margin bottom */
+mb-16  /* 64px - Section margin bottom */
+```
+
+**Rule**: Stick to multiples of 4 (4, 8, 12, 16, 24, 32, 48, 64, 96).
+
+---
+
+## 4. TYPOGRAPHY SCALE
+
+```tsx
+// Page Title (H1)
+<h1 className="text-4xl md:text-6xl font-bold text-white mb-8">
+  Page Title
+</h1>
+
+// Section Title (H2)
+<h2 className="text-3xl md:text-5xl font-bold text-white mb-6">
+  Section Title <span className="text-[#80cca5]">Accent</span>
+</h2>
+
+// Subsection (H3)
+<h3 className="text-2xl md:text-4xl font-bold text-white mb-4">
+  Subsection
+</h3>
+
+// Body Text
+<p className="text-lg text-slate-300 mb-4">
+  Body text goes here
+</p>
+
+// Muted Text
+<p className="text-sm text-slate-400">
+  Secondary information
+</p>
+
+// Accent Text
+<p className="text-lg font-semibold text-[#80cca5]">
+  Call to action text
+</p>
+```
+
+---
+
+## 5. BUTTONS & LINKS
+
+```tsx
+// Primary CTA Button
+<button className="
+  px-8 py-4 
+  rounded-full 
+  bg-[#80cca5] 
+  hover:bg-[#6bb890] 
+  text-white 
+  font-semibold 
+  transition-all 
+  shadow-lg 
+  hover:shadow-xl
+">
+  Primary Action
+</button>
+
+// Secondary Button
+<button className="
+  px-6 py-3 
+  rounded-full 
+  bg-white/[0.02] 
+  border border-white/10 
+  hover:border-[#80cca5]/30 
+  text-white 
+  font-medium 
+  transition-all
+">
+  Secondary Action
+</button>
+
+// Link
+<a href="#" className="text-[#80cca5] hover:text-[#6bb890] transition-colors">
+  Link Text
+</a>
+```
+
+---
+
+## 6. FORM INPUTS
+
+```tsx
+// Text Input
+<input 
+  type="text"
+  className="
+    w-full 
+    px-4 py-3 
+    rounded-lg 
+    border border-[#80cca5]/20 
+    bg-slate-900/50 
+    text-white 
+    placeholder:text-slate-500 
+    focus:ring-2 
+    focus:ring-[#80cca5] 
+    focus:border-transparent
+  "
+  placeholder="Enter text"
+/>
+
+// Textarea
+<textarea 
+  className="
+    w-full 
+    px-4 py-3 
+    rounded-lg 
+    border border-[#80cca5]/20 
+    bg-slate-900/50 
+    text-white 
+    placeholder:text-slate-500 
+    focus:ring-2 
+    focus:ring-[#80cca5] 
+    focus:border-transparent 
+    resize-none
+  "
+  rows={4}
+/>
+
+// Label
+<label className="text-slate-200 font-medium mb-2 block">
+  Field Label
+</label>
+```
+
+---
+
+## 7. COMMON LAYOUTS
+
+### Hero Section
+
+```tsx
+<PremiumSection>
+  <div className="max-w-4xl mx-auto text-center">
+    <PremiumHeading as="h1" accent="AI">
+      Build Production
+    </PremiumHeading>
+    <p className="text-xl text-slate-300 mb-8">
+      Your subtitle goes here
+    </p>
+    <button className="px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all shadow-lg">
+      Get Started
+    </button>
+  </div>
+</PremiumSection>
+```
+
+### Feature Grid
+
+```tsx
+<PremiumSection>
+  <div className="text-center mb-16">
+    <PremiumHeading accent="Features">
+      Powerful
+    </PremiumHeading>
+  </div>
+  <div className="grid md:grid-cols-3 gap-8">
+    {features.map((feature) => (
+      <PremiumCard key={feature.id}>
+        <Icon className="size-12 text-[#80cca5] mb-4" />
+        <h3 className="text-xl font-bold text-white mb-2">
+          {feature.title}
+        </h3>
+        <p className="text-slate-300">
+          {feature.description}
+        </p>
+      </PremiumCard>
+    ))}
+  </div>
+</PremiumSection>
+```
+
+### CTA Section
+
+```tsx
+<PremiumSection>
+  <div className="max-w-3xl mx-auto">
+    <div className="text-center mb-12">
+      <PremiumHeading accent="Started">
+        Get
+      </PremiumHeading>
+      <p className="text-xl text-slate-300">
+        Join thousands of users
+      </p>
+    </div>
+    <PremiumCard className="p-8 md:p-12">
+      <form className="space-y-6">
+        <input 
+          type="email"
+          placeholder="you@example.com"
+          className="w-full px-4 py-3 rounded-lg border border-[#80cca5]/20 bg-slate-900/50 text-white placeholder:text-slate-500 focus:ring-2 focus:ring-[#80cca5] focus:border-transparent"
+        />
+        <button className="w-full px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all">
+          Sign Up
+        </button>
+      </form>
+    </PremiumCard>
+  </div>
+</PremiumSection>
+```
+
+---
+
+## 8. GLASSMORPHISM RULES
+
+✅ **DO**:
+- Use `bg-white/[0.02]` for card backgrounds
+- Add `backdrop-blur-xl` for blur effect
+- Use `border-white/10` for subtle borders
+- Keep opacity LOW (0.02 to 0.04)
+- Layer multiple glass surfaces
+
+❌ **DON'T**:
+- Use high opacity (breaks glass effect)
+- Skip backdrop blur (looks flat)
+- Use on light backgrounds (invisible)
+- Overuse (reserve for cards/panels)
+
+**Example**:
+```tsx
+<div className="bg-white/[0.02] border border-white/10 backdrop-blur-xl">
+  Glass content
+</div>
+```
+
+---
+
+## 9. RADIAL GLOW USAGE
+
+### When to Use:
+- ✅ Hero sections (large, centered)
+- ✅ Important CTAs (behind forms)
+- ✅ Section breaks (corner glows)
+- ❌ Every section (overwhelming)
+- ❌ Small components (too subtle)
+
+### Sizes:
+- **Small**: 400px (subtle accent)
+- **Medium**: 600px (default)
+- **Large**: 800px (hero sections)
+
+### Positioning:
+```tsx
+// Centered
+<RadialGlow className="top-1/2 left-1/2" />
+
+// Top-left
+<RadialGlow className="top-0 left-0" />
+
+// Bottom-right
+<RadialGlow className="bottom-0 right-0" />
+```
+
+---
+
+## 10. RESPONSIVE DESIGN
+
+```tsx
+// Mobile: Stack, Desktop: Grid
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
+  {/* Items */}
+</div>
+
+// Mobile: Full width, Desktop: Constrained
+<div className="w-full lg:max-w-4xl mx-auto">
+  {/* Content */}
+</div>
+
+// Mobile: Small text, Desktop: Large text
+<h2 className="text-3xl md:text-5xl">
+  Responsive Heading
+</h2>
+
+// Mobile: Center, Desktop: Left
+<div className="text-center lg:text-left">
+  {/* Content */}
+</div>
+```
+
+**Breakpoints**:
+- `sm`: 640px (tablets)
+- `md`: 768px (tablets/small laptops)
+- `lg`: 1024px (laptops)
+- `xl`: 1280px (desktops)
+
+---
+
+## 11. ANIMATIONS
+
+### Hover Effects
+
+```tsx
+// Card hover
+<div className="transition-all duration-300 hover:scale-[1.02]">
+  Card content
+</div>
+
+// Button hover
+<button className="transition-colors duration-200 hover:bg-[#6bb890]">
+  Button
+</button>
+
+// Image hover
+<img className="transition-transform duration-700 hover:scale-105" />
+```
+
+### Scroll Reveal (Optional)
+
+```tsx
+// Install: npm install react-intersection-observer
+import { useInView } from 'react-intersection-observer'
+
+function Component() {
+  const { ref, inView } = useInView({ triggerOnce: true, threshold: 0.1 })
+  
+  return (
+    <div 
+      ref={ref}
+      className={`transition-all duration-700 ${
+        inView ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-8'
+      }`}
+    >
+      Content
+    </div>
+  )
+}
+```
+
+---
+
+## 12. ACCESSIBILITY CHECKLIST
+
+✅ **Color Contrast**:
+- White on `#0a0f0d`: 21:1 (AAA) ✅
+- `slate-300` on `#0a0f0d`: 12.6:1 (AAA) ✅
+- `#80cca5` on `#0a0f0d`: 7.8:1 (AAA) ✅
+
+✅ **Focus States**:
+```tsx
+<button className="focus:ring-2 focus:ring-[#80cca5] focus:outline-none">
+  Button
+</button>
+```
+
+✅ **Semantic HTML**:
+```tsx
+<nav>
+  <ul>
+    <li><a href="#">Link</a></li>
+  </ul>
+</nav>
+```
+
+✅ **Alt Text**:
+```tsx
+<img src="..." alt="Descriptive text" />
+```
+
+---
+
+## 13. QUICK WINS (Instant Premium Feel)
+
+1. **Replace all backgrounds** with `#0a0f0d`
+2. **Use only white and slate-300** for text
+3. **Make all CTAs** `#80cca5` green
+4. **Add backdrop-blur-xl** to all cards
+5. **Use rounded-2xl** for cards, `rounded-full` for buttons
+6. **Add one radial glow** to hero section
+7. **Increase padding** (py-24 for sections, p-8 for cards)
+8. **Add hover effects** to all interactive elements
+
+---
+
+## 14. COMMON MISTAKES TO AVOID
+
+❌ **Don't**:
+- Use light backgrounds (`bg-white`, `bg-slate-100`)
+- Use `dark:` variants (this is dark-only)
+- Mix multiple accent colors
+- Use high-opacity glass (`bg-white/50`)
+- Skip backdrop blur on glass elements
+- Use small padding (looks cramped)
+- Forget hover states
+- Ignore mobile layout
+
+✅ **Do**:
+- Stick to the color palette
+- Use consistent spacing (multiples of 4)
+- Add subtle animations
+- Test on mobile first
+- Keep glass opacity low
+- Use radial glows sparingly
+- Maintain high contrast for text
+
+---
+
+## 15. COPY-PASTE STARTER TEMPLATE
+
+```tsx
+import React from 'react'
+
+// 1. Copy the 4 core components (Section A-D above)
+// 2. Use this page structure:
+export default function Page() {
+  return (
+    <div className="min-h-screen bg-[#0a0f0d]">
+      {/* Hero */}
+      <PremiumSection>
+        <div className="max-w-4xl mx-auto text-center">
+          <PremiumHeading as="h1" accent="Premium">
+            Your
+          </PremiumHeading>
+          <p className="text-xl text-slate-300 mb-8">
+            Subtitle goes here
+          </p>
+          <button className="px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all shadow-lg">
+            Get Started
+          </button>
+        </div>
+      </PremiumSection>
+
+      {/* Features */}
+      <PremiumSection>
+        <div className="text-center mb-16">
+          <PremiumHeading accent="Features">
+            Amazing
+          </PremiumHeading>
+        </div>
+        <div className="grid md:grid-cols-3 gap-8">
+          <PremiumCard>
+            <h3 className="text-xl font-bold text-white mb-2">Feature 1</h3>
+            <p className="text-slate-300">Description</p>
+          </PremiumCard>
+          <PremiumCard>
+            <h3 className="text-xl font-bold text-white mb-2">Feature 2</h3>
+            <p className="text-slate-300">Description</p>
+          </PremiumCard>
+          <PremiumCard>
+            <h3 className="text-xl font-bold text-white mb-2">Feature 3</h3>
+            <p className="text-slate-300">Description</p>
+          </PremiumCard>
+        </div>
+      </PremiumSection>
+
+      {/* CTA */}
+      <PremiumSection>
+        <div className="max-w-3xl mx-auto text-center">
+          <PremiumHeading accent="Started">
+            Get
+          </PremiumHeading>
+          <PremiumCard className="p-8 md:p-12">
+            <form className="space-y-6">
+              <input 
+                type="email"
+                placeholder="you@example.com"
+                className="w-full px-4 py-3 rounded-lg border border-[#80cca5]/20 bg-slate-900/50 text-white placeholder:text-slate-500 focus:ring-2 focus:ring-[#80cca5] focus:border-transparent"
+              />
+              <button className="w-full px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all">
+                Sign Up
+              </button>
+            </form>
+          </PremiumCard>
+        </div>
+      </PremiumSection>
+    </div>
+  )
+}
+```
+
+---
+
+## 16. FINAL CHECKLIST
+
+Before launching, verify:
+
+- [ ] All backgrounds are `#0a0f0d` or `black`
+- [ ] All headings are `text-white`
+- [ ] All body text is `text-slate-300`
+- [ ] All CTAs are `#80cca5` green
+- [ ] All cards have `backdrop-blur-xl`
+- [ ] All cards use `bg-white/[0.02]`
+- [ ] All buttons have hover states
+- [ ] All forms have focus states
+- [ ] Spacing uses multiples of 4
+- [ ] Mobile layout tested
+- [ ] Radial glows are subtle (not overwhelming)
+- [ ] No light mode variants (`dark:`)
+- [ ] Contrast ratios meet WCAG AA minimum
+
+---
+
+## DONE! 🎉
+
+You now have everything needed to create a premium dark UI.
+
+**Time to premium**: 30-60 minutes
+**Maintenance**: Easy (4 components, 1 color palette)
+**Scalability**: High (reusable components)
+
+**Questions?** Reference the full guide: `.opencode/context/ui/web/design/guides/premium-dark-ui-system.md`

.opencode/context/ui/web/design/guides/premium-dark-ui-visual-reference.md

@@ -0,0 +1,513 @@
+# Premium Dark UI - Visual Reference
+
+Quick visual guide for the premium dark aesthetic.
+
+---
+
+## COLOR SWATCHES
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ BACKGROUNDS                                             │
+├─────────────────────────────────────────────────────────┤
+│ #0a0f0d  ████████  Deep Dark (Main)                     │
+│ #000000  ████████  Pure Black (Alternate)               │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ ACCENT                                                  │
+├─────────────────────────────────────────────────────────┤
+│ #80cca5  ████████  Mint Green (Primary)                 │
+│ #6bb890  ████████  Darker Green (Hover)                 │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ GLASS                                                   │
+├─────────────────────────────────────────────────────────┤
+│ rgba(255,255,255,0.02)  ░░░░░░░░  Glass Background      │
+│ rgba(255,255,255,0.10)  ▒▒▒▒▒▒▒▒  Glass Border         │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ TEXT                                                    │
+├─────────────────────────────────────────────────────────┤
+│ #ffffff  ████████  Headings (White)                     │
+│ #cbd5e1  ████████  Body (Slate-300)                     │
+│ #94a3b8  ████████  Muted (Slate-400)                    │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## TYPOGRAPHY HIERARCHY
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ H1 - Page Title                                         │
+│ text-4xl md:text-6xl (36px → 60px)                      │
+│ font-bold, text-white, mb-8                             │
+├─────────────────────────────────────────────────────────┤
+│ H2 - Section Title                                      │
+│ text-3xl md:text-5xl (30px → 48px)                      │
+│ font-bold, text-white, mb-6                             │
+├─────────────────────────────────────────────────────────┤
+│ H3 - Subsection                                         │
+│ text-2xl md:text-4xl (24px → 36px)                      │
+│ font-bold, text-white, mb-4                             │
+├─────────────────────────────────────────────────────────┤
+│ Body - Large                                            │
+│ text-lg (18px)                                          │
+│ text-slate-300                                          │
+├─────────────────────────────────────────────────────────┤
+│ Body - Regular                                          │
+│ text-base (16px)                                        │
+│ text-slate-300                                          │
+├─────────────────────────────────────────────────────────┤
+│ Body - Small                                            │
+│ text-sm (14px)                                          │
+│ text-slate-400                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## COMPONENT ANATOMY
+
+### Glass Card
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+│ ░  ┌─────────────────────────────────────────────┐  ░ │
+│ ░  │  border-white/10                            │  ░ │
+│ ░  │  rounded-2xl                                │  ░ │
+│ ░  │                                             │  ░ │
+│ ░  │  Content goes here                          │  ░ │
+│ ░  │  backdrop-blur-xl                           │  ░ │
+│ ░  │                                             │  ░ │
+│ ░  └─────────────────────────────────────────────┘  ░ │
+│ ░                                                     ░ │
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+└─────────────────────────────────────────────────────────┘
+   bg-white/[0.02] (very subtle)
+```
+
+### Button
+
+```
+┌──────────────────────────────────────┐
+│  px-8 py-4                           │
+│  ┌────────────────────────────────┐  │
+│  │  Button Text                   │  │ ← text-white
+│  └────────────────────────────────┘  │
+│  rounded-full                        │
+│  bg-[#80cca5]                        │
+└──────────────────────────────────────┘
+```
+
+### Radial Glow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                      ╭───────────╮                      │
+│                    ╱               ╲                    │
+│                  ╱                   ╲                  │
+│                ╱    Radial Glow       ╲                 │
+│              ╱      (#80cca5)           ╲               │
+│             │       opacity: 0.15         │              │
+│              ╲      600px × 600px        ╱              │
+│                ╲                       ╱                │
+│                  ╲                   ╱                  │
+│                    ╲               ╱                    │
+│                      ╰───────────╯                      │
+│                                                         │
+│         ┌─────────────────────────┐                     │
+│         │  Content (z-10)         │                     │
+│         │  Sits above glow        │                     │
+│         └─────────────────────────┘                     │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## LAYOUT PATTERNS
+
+### Hero Section
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                    [Radial Glow]                        │
+│                                                         │
+│              ┌─────────────────────┐                    │
+│              │   H1 Title          │                    │
+│              │   with Accent       │                    │
+│              └─────────────────────┘                    │
+│                                                         │
+│              ┌─────────────────────┐                    │
+│              │   Subtitle text     │                    │
+│              └─────────────────────┘                    │
+│                                                         │
+│              ┌─────────────────────┐                    │
+│              │   [CTA Button]      │                    │
+│              └─────────────────────┘                    │
+│                                                         │
+│ max-w-4xl mx-auto text-center                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Feature Grid (3 columns)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│              ┌─────────────────────┐                    │
+│              │   Section Title     │                    │
+│              └─────────────────────┘                    │
+│                                                         │
+│  ┌───────────┐  ┌───────────┐  ┌───────────┐          │
+│  │ ░░░░░░░░░ │  │ ░░░░░░░░░ │  │ ░░░░░░░░░ │          │
+│  │ ░ Card 1 ░ │  │ ░ Card 2 ░ │  │ ░ Card 3 ░ │          │
+│  │ ░░░░░░░░░ │  │ ░░░░░░░░░ │  │ ░░░░░░░░░ │          │
+│  └───────────┘  └───────────┘  └───────────┘          │
+│                                                         │
+│  grid md:grid-cols-3 gap-8                             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### CTA Section
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                    [Radial Glow]                        │
+│                                                         │
+│              ┌─────────────────────┐                    │
+│              │   H2 Title          │                    │
+│              └─────────────────────┘                    │
+│                                                         │
+│         ┌─────────────────────────────┐                 │
+│         │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░ │                 │
+│         │ ░                         ░ │                 │
+│         │ ░  [Email Input]          ░ │                 │
+│         │ ░                         ░ │                 │
+│         │ ░  [Submit Button]        ░ │                 │
+│         │ ░                         ░ │                 │
+│         │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░ │                 │
+│         └─────────────────────────────┘                 │
+│                Glass Card (p-12)                        │
+│                                                         │
+│ max-w-3xl mx-auto                                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## SPACING SCALE
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Tailwind  │ Pixels │ Usage                              │
+├─────────────────────────────────────────────────────────┤
+│ py-4      │ 16px   │ Small spacing                      │
+│ py-8      │ 32px   │ Medium spacing                     │
+│ py-12     │ 48px   │ Large spacing                      │
+│ py-24     │ 96px   │ Section spacing                    │
+├─────────────────────────────────────────────────────────┤
+│ px-4      │ 16px   │ Mobile padding                     │
+│ px-8      │ 32px   │ Card padding                       │
+│ px-12     │ 48px   │ Large card padding                 │
+├─────────────────────────────────────────────────────────┤
+│ gap-4     │ 16px   │ Small gaps                         │
+│ gap-8     │ 32px   │ Medium gaps                        │
+│ gap-12    │ 48px   │ Large gaps                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## RESPONSIVE BREAKPOINTS
+
+```
+Mobile (< 768px)
+┌─────────────────────────┐
+│                         │
+│   Content               │
+│   Stacked               │
+│   Full Width            │
+│                         │
+└─────────────────────────┘
+
+Desktop (> 1024px)
+┌─────────────────────────────────────┐
+│                                     │
+│   Content                           │
+│   3 Columns                         │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+**Breakpoint Classes**:
+- `sm:` - 640px (small tablets)
+- `md:` - 768px (tablets)
+- `lg:` - 1024px (laptops)
+- `xl:` - 1280px (desktops)
+
+---
+
+## HOVER STATES
+
+### Button Hover
+
+```
+Normal State:
+┌────────────────┐
+│  bg-[#80cca5]  │
+│  shadow-lg     │
+└────────────────┘
+
+Hover State:
+┌────────────────┐
+│  bg-[#6bb890]  │ ← Darker green
+│  shadow-xl     │ ← Larger shadow
+└────────────────┘
+```
+
+### Card Hover
+
+```
+Normal State:
+┌────────────────┐
+│ bg-white/[0.02]│
+│ border-white/10│
+└────────────────┘
+
+Hover State:
+┌────────────────┐
+│ bg-white/[0.04]│ ← Slightly brighter
+│ border-[#80cca5]/30 │ ← Green tint
+│ scale-[1.02]   │ ← Subtle scale
+└────────────────┘
+```
+
+---
+
+## LAYERING & DEPTH
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Layer 1 (Background)                                    │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ bg-[#0a0f0d]                                        │ │
+│ │                                                     │ │
+│ │   Layer 2 (Glass Card)                              │ │
+│ │   ┌─────────────────────────────────┐               │ │
+│ │   │ bg-white/[0.02]                 │               │ │
+│ │   │ backdrop-blur-xl                │               │ │
+│ │   │                                 │               │ │
+│ │   │   Layer 3 (Nested Glass)        │               │ │
+│ │   │   ┌─────────────────────┐       │               │ │
+│ │   │   │ bg-white/[0.02]     │       │               │ │
+│ │   │   │ border-white/10     │       │               │ │
+│ │   │   └─────────────────────┘       │               │ │
+│ │   │                                 │               │ │
+│ │   └─────────────────────────────────┘               │ │
+│ │                                                     │ │
+│ └─────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## GLOW POSITIONING
+
+```
+Centered Glow:
+┌─────────────────────────────────────┐
+│                                     │
+│              ╭───────╮              │
+│            ╱           ╲            │
+│          ╱               ╲          │
+│        ╱        Glow       ╲        │
+│       │                     │       │
+│        ╲                   ╱        │
+│          ╲               ╱          │
+│            ╲           ╱            │
+│              ╰───────╯              │
+│                                     │
+└─────────────────────────────────────┘
+
+Corner Glow:
+┌─────────────────────────────────────┐
+│    ╭───────╮                        │
+│  ╱           ╲                      │
+│ │    Glow     │                     │
+│  ╲           ╱                      │
+│    ╰───────╯                        │
+│                                     │
+│                                     │
+│                                     │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+---
+
+## ANIMATION TIMING
+
+```
+Fast (200ms)
+├─ Button color changes
+└─ Link hover
+
+Medium (300ms)
+├─ Card hover effects
+└─ Form focus states
+
+Slow (700ms)
+├─ Image zoom
+├─ Scroll reveals
+└─ Page transitions
+```
+
+**Easing**: Use `ease-in-out` or default `ease` for smooth transitions.
+
+---
+
+## CONTRAST RATIOS
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Combination              │ Ratio  │ WCAG Level          │
+├─────────────────────────────────────────────────────────┤
+│ White on #0a0f0d         │ 21:1   │ AAA ✅              │
+│ Slate-300 on #0a0f0d     │ 12.6:1 │ AAA ✅              │
+│ #80cca5 on #0a0f0d       │ 7.8:1  │ AAA ✅              │
+│ Slate-400 on #0a0f0d     │ 6.2:1  │ AA Large Text ⚠️    │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## GLOW SIZES
+
+```
+Small (400px):
+      ╭─────╮
+    ╱         ╲
+   │   Glow    │
+    ╲         ╱
+      ╰─────╯
+
+Medium (600px):
+       ╭───────╮
+     ╱           ╲
+   ╱      Glow     ╲
+  │                 │
+   ╲               ╱
+     ╲           ╱
+       ╰───────╯
+
+Large (800px):
+        ╭─────────╮
+      ╱             ╲
+    ╱                 ╲
+   │       Glow        │
+    ╲                 ╱
+      ╲             ╱
+        ╰─────────╯
+```
+
+**Usage**:
+- Small: Subtle accents, corner glows
+- Medium: Standard sections
+- Large: Hero sections, important CTAs
+
+---
+
+## FORM STATES
+
+### Input States
+
+```
+Normal:
+┌────────────────────────────────────┐
+│ border-[#80cca5]/20                │
+│ bg-slate-900/50                    │
+└────────────────────────────────────┘
+
+Focus:
+┌────────────────────────────────────┐
+│ ring-2 ring-[#80cca5]              │ ← Green ring
+│ border-transparent                 │
+└────────────────────────────────────┘
+
+Error:
+┌────────────────────────────────────┐
+│ border-red-500                     │
+│ ring-2 ring-red-500/50             │
+└────────────────────────────────────┘
+```
+
+---
+
+## ICON SIZES
+
+```
+▪ size-4 (16px)  ▪
+▪ size-6 (24px)  ▪
+▪ size-8 (32px)  ▪
+▪ size-10 (40px) ▪
+▪ size-12 (48px) ▪
+```
+
+**Usage**:
+- `size-4`: Inline icons, badges
+- `size-6`: Button icons
+- `size-10-12`: Feature icons, decorative
+
+---
+
+## SHADOW SCALE
+
+```
+sm:  shadow-sm   ▁
+md:  shadow      ▂
+lg:  shadow-lg   ▃
+xl:  shadow-xl   ▄
+2xl: shadow-2xl  ▅
+```
+
+**Usage**:
+- `shadow-lg`: Default for cards
+- `shadow-xl`: Hover state for cards
+- `shadow-2xl`: Modals, dropdowns
+
+---
+
+## QUICK REFERENCE CARD
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ PREMIUM DARK UI - CHEAT SHEET                           │
+├─────────────────────────────────────────────────────────┤
+│ Background:  #0a0f0d or black                           │
+│ Text:        white (headings), slate-300 (body)         │
+│ Accent:      #80cca5 (green)                            │
+│ Glass:       bg-white/[0.02], backdrop-blur-xl          │
+│ Borders:     border-white/10                            │
+│ Spacing:     Multiples of 4 (4, 8, 12, 24, 48, 96)      │
+│ Rounded:     rounded-2xl (cards), rounded-full (buttons)│
+│ Shadows:     shadow-lg (default), shadow-xl (hover)     │
+│ Transitions: duration-300 (default)                     │
+│ Glow:        600px, opacity 0.15 (default)              │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## DONE! 🎨
+
+Use this visual reference alongside the Quick Start Guide for fast implementation.

.opencode/context/ui/web/design/navigation.md

@@ -6,7 +6,7 @@ description: "Advanced web UI patterns - scroll animations, visual effects, and
 
 **Purpose**: Advanced web UI patterns - scroll animations, visual effects, and interactive design
 
-**Last Updated**: 2026-01-07
+**Last Updated**: 2026-01-31
 
 ---
 
@@ -26,6 +26,8 @@ description: "Advanced web UI patterns - scroll animations, visual effects, and
 | File | Description | Priority |
 |------|-------------|----------|
 | [building-scrollytelling-pages.md](guides/building-scrollytelling-pages.md) | Complete implementation guide | high |
+| [premium-dark-ui-quick-start.md](guides/premium-dark-ui-quick-start.md) | Premium dark UI design system quick start | high |
+| [premium-dark-ui-visual-reference.md](guides/premium-dark-ui-visual-reference.md) | Visual reference for premium dark UI | medium |
 
 ### Lookup
 | File | Description | Priority |
@@ -47,6 +49,10 @@ description: "Advanced web UI patterns - scroll animations, visual effects, and
 3. Load `examples/scrollytelling-headphone.md` (see full code)
 4. Reference `guides/building-scrollytelling-pages.md` (step-by-step)
 
+**For premium dark UI design**:
+1. Load `guides/premium-dark-ui-quick-start.md` (implementation guide)
+2. Reference `guides/premium-dark-ui-visual-reference.md` (visual patterns)
+
 ---
 
 ## Scope
@@ -56,6 +62,8 @@ This subcategory covers:
 - ✅ Canvas-based rendering
 - ✅ Framer Motion patterns
 - ✅ Image sequence generation
+- ✅ Premium dark UI design system
+- ✅ Glassmorphism patterns
 - ⏳ CSS animations (future)
 - ⏳ SVG animations (future)
 - ⏳ WebGL effects (future)
@@ -77,7 +85,7 @@ This subcategory covers:
 ## Statistics
 - Concepts: 1
 - Examples: 1
-- Guides: 1
+- Guides: 3
 - Lookup: 1
 - Errors: 0
-- **Total**: 4 files
+- **Total**: 6 files