claude-code-arcane 2.9.7 → 2.9.9

package/skills/senior-prompt-engineer/SKILL.md

@@ -23,12 +23,12 @@ python scripts/agent_orchestrator.py agent_config.yaml --visualize       # Visua
 
 ### 1. Prompt Optimizer
 
-Analyzes prompts for token efficiency, clarity, and structure. Generates optimized versions.
+Static checks for clarity and structure, with an approximate token count (characters / 4). `--optimize` only normalizes whitespace; the real rewrite is yours.
 
 ```bash
 python scripts/prompt_optimizer.py prompt.txt --analyze          # Full analysis
-python scripts/prompt_optimizer.py prompt.txt --optimize         # Generate optimized version
-python scripts/prompt_optimizer.py prompt.txt --tokens --model gpt-4  # Token count
+python scripts/prompt_optimizer.py prompt.txt --optimize         # Normalize whitespace
+python scripts/prompt_optimizer.py prompt.txt --tokens           # Approximate token count
 python scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json
 ```
 
@@ -50,7 +50,7 @@ Parses agent definitions and visualizes execution flows. Validates tool configur
 python scripts/agent_orchestrator.py agent.yaml --validate       # Validate config
 python scripts/agent_orchestrator.py agent.yaml --visualize      # Show workflow (ASCII)
 python scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid  # Mermaid
-python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimation
+python scripts/agent_orchestrator.py agent.yaml --estimate-cost --price-in 4 --price-out 20  # Tokens; dollars with your current prices (USD/Mtok)
 ```
 
 ## Prompt Engineering Workflows
@@ -65,7 +65,7 @@ python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimat
 |-------|---------|
 | Ambiguous output | Add explicit format specification |
 | Too verbose | Extract to few-shot examples |
-| Inconsistent results | Add role/persona framing |
+| Inconsistent results | Add 2-3 varied examples and state the success criteria |
 | Missing edge cases | Add constraint boundaries |
 
 4. **Optimize**: `python scripts/prompt_optimizer.py current_prompt.txt --optimize --output optimized.txt`
@@ -77,15 +77,15 @@ python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimat
 1. Define task clearly (input format, output format)
 2. Select 3-5 diverse examples: simple case, edge case, complex case, negative case
 3. Format consistently
-4. Validate: `python scripts/prompt_optimizer.py prompt_with_examples.txt --validate-examples`
+4. Check what the prompt contains: `python scripts/prompt_optimizer.py prompt_with_examples.txt --extract-examples`
 5. Test with held-out cases
 
 ### Structured Output Design
 
 1. Define JSON/XML schema with types, constraints, enums
-2. Include schema description in prompt
-3. Add format enforcement: "Respond ONLY with valid JSON. Start with { and end with }"
-4. Validate: `python scripts/prompt_optimizer.py structured_prompt.txt --validate-schema schema.json`
+2. Pass the schema through the API's structured outputs (`output_config.format` on Claude) so the response is guaranteed to match it; do not rely on "respond ONLY with valid JSON" in the prompt
+3. Describe in the prompt what each field means, not the JSON syntax
+4. Validate the parsed result against the schema in code before using it
 
 ## Reference Documentation
 
@@ -103,6 +103,6 @@ python scripts/agent_orchestrator.py agent.yaml --estimate-cost  # Token estimat
 |---------|-------------|---------|
 | **Zero-shot** | Simple, well-defined tasks | "Classify this email as spam or not spam" |
 | **Few-shot** | Complex tasks, consistent format | Provide 3-5 examples before task |
-| **Chain-of-Thought** | Reasoning, math, multi-step | "Think step by step..." |
+| **Reasoning depth** | Reasoning, math, multi-step | Models with adaptive thinking: raise `effort`. Models without it: "Think step by step..." |
 | **Role Prompting** | Expertise, specific perspective | "You are an expert tax accountant..." |
 | **Structured Output** | Need parseable JSON/XML | Include schema + format enforcement |

package/skills/senior-prompt-engineer/references/prompt_engineering_patterns.md

@@ -164,7 +164,7 @@ The 7 apples cost $11.20
 | Reasoning chain | "Explain your reasoning" | Justification needed |
 
 **Zero-shot CoT:**
-Simply append "Let's think step by step." to any prompt.
+Append "Let's think step by step." only on models without built-in thinking. On models with adaptive thinking, control depth with `effort`; asking for the reasoning in the output can be declined as reasoning extraction.
 
 ---
 

package/skills/senior-prompt-engineer/scripts/agent_orchestrator.py

@@ -55,7 +55,7 @@ class AgentConfig:
     max_iterations: int = 10
     system_prompt: str = ""
     temperature: float = 0.7
-    model: str = "gpt-4"
+    model: str = ""
 
 
 @dataclass
@@ -177,7 +177,7 @@ def load_config(path: Path) -> AgentConfig:
         max_iterations=int(data.get('max_iterations', 10)),
         system_prompt=data.get('system_prompt', ''),
         temperature=float(data.get('temperature', 0.7)),
-        model=data.get('model', 'gpt-4')
+        model=data.get('model', '')
     )
 
 
@@ -369,44 +369,39 @@ def generate_mermaid_diagram(config: AgentConfig) -> str:
     return '\n'.join(lines)
 
 
-def estimate_cost(config: AgentConfig, runs: int = 100) -> Dict[str, Any]:
-    """Estimate token costs for agent runs"""
+def estimate_cost(config: AgentConfig, runs: int = 100,
+                  price_in: Optional[float] = None, price_out: Optional[float] = None) -> Dict[str, Any]:
+    """Estimate tokens per run; dollars only when the caller supplies current prices.
+
+    Prices are USD per million tokens. They are not built in because provider prices
+    change and a stale table gives confidently wrong numbers.
+    """
     validation = validate_agent(config)
     min_tokens, max_tokens = validation.estimated_tokens_per_run
 
-    # Cost per 1K tokens
-    costs = {
-        'gpt-4': {'input': 0.03, 'output': 0.06},
-        'gpt-4-turbo': {'input': 0.01, 'output': 0.03},
-        'gpt-3.5-turbo': {'input': 0.0005, 'output': 0.0015},
-        'claude-3-opus': {'input': 0.015, 'output': 0.075},
-        'claude-3-sonnet': {'input': 0.003, 'output': 0.015},
-    }
-
-    model_cost = costs.get(config.model, costs['gpt-4'])
-
-    # Assume 60% input, 40% output
-    input_tokens = min_tokens * 0.6
-    output_tokens = min_tokens * 0.4
+    def dollars(tokens: float) -> Optional[float]:
+        if price_in is None or price_out is None:
+            return None
+        # Assume 60% input, 40% output
+        return (tokens * 0.6 * price_in + tokens * 0.4 * price_out) / 1_000_000
 
-    cost_per_run_min = (input_tokens / 1000 * model_cost['input'] +
-                        output_tokens / 1000 * model_cost['output'])
+    per_run_min, per_run_max = dollars(min_tokens), dollars(max_tokens)
+    monthly_runs = runs * 30
 
-    input_tokens_max = max_tokens * 0.6
-    output_tokens_max = max_tokens * 0.4
-    cost_per_run_max = (input_tokens_max / 1000 * model_cost['input'] +
-                        output_tokens_max / 1000 * model_cost['output'])
-
-    return {
-        'model': config.model,
+    result = {
+        'model': config.model or None,
         'tokens_per_run': {'min': min_tokens, 'max': max_tokens},
-        'cost_per_run': {'min': round(cost_per_run_min, 4), 'max': round(cost_per_run_max, 4)},
         'estimated_monthly': {
-            'runs': runs * 30,
-            'cost_min': round(cost_per_run_min * runs * 30, 2),
-            'cost_max': round(cost_per_run_max * runs * 30, 2)
-        }
+            'runs': monthly_runs,
+            'tokens_min': min_tokens * monthly_runs,
+            'tokens_max': max_tokens * monthly_runs,
+        },
     }
+    if per_run_min is not None:
+        result['cost_per_run'] = {'min': round(per_run_min, 4), 'max': round(per_run_max, 4)}
+        result['estimated_monthly']['cost_min'] = round(per_run_min * monthly_runs, 2)
+        result['estimated_monthly']['cost_max'] = round(per_run_max * monthly_runs, 2)
+    return result
 
 
 def format_validation_report(config: AgentConfig, result: ValidationResult) -> str:
@@ -461,6 +456,9 @@ def format_validation_report(config: AgentConfig, result: ValidationResult) -> s
 
 
 def main():
+    # The report uses emoji; a Windows console defaults to cp1252 and cannot print them.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
     parser = argparse.ArgumentParser(
         description="Agent Orchestrator - Design and validate agent workflows",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -469,13 +467,13 @@ Examples:
   %(prog)s agent.yaml --validate
   %(prog)s agent.yaml --visualize
   %(prog)s agent.yaml --visualize --format mermaid
-  %(prog)s agent.yaml --estimate-cost --runs 100
+  %(prog)s agent.yaml --estimate-cost --runs 100 --price-in 4 --price-out 20
 
 Agent config format (YAML):
 
 name: research_assistant
 pattern: react
-model: gpt-4
+model: claude-opus-5-5
 max_iterations: 10
 tools:
   - name: web_search
@@ -493,6 +491,8 @@ tools:
                        help='Visualization format (default: ascii)')
     parser.add_argument('--estimate-cost', '-e', action='store_true', help='Estimate token costs')
     parser.add_argument('--runs', '-r', type=int, default=100, help='Daily runs for cost estimation')
+    parser.add_argument('--price-in', type=float, help='Current input price, USD per million tokens')
+    parser.add_argument('--price-out', type=float, help='Current output price, USD per million tokens')
     parser.add_argument('--output', '-o', help='Output file path')
     parser.add_argument('--json', '-j', action='store_true', help='Output as JSON')
 
@@ -534,18 +534,21 @@ tools:
 
     # Cost estimation
     if args.estimate_cost:
-        costs = estimate_cost(config, args.runs)
+        costs = estimate_cost(config, args.runs, args.price_in, args.price_out)
         if args.json:
             output_parts.append(json.dumps(costs, indent=2))
         else:
             output_parts.append("")
             output_parts.append("💰 COST ESTIMATION")
-            output_parts.append(f"  Model: {costs['model']}")
+            output_parts.append(f"  Model: {costs['model'] or '(not set)'}")
             output_parts.append(f"  Tokens per run: {costs['tokens_per_run']['min']:,} - {costs['tokens_per_run']['max']:,}")
-            output_parts.append(f"  Cost per run: ${costs['cost_per_run']['min']:.4f} - ${costs['cost_per_run']['max']:.4f}")
-            output_parts.append(f"  Monthly ({costs['estimated_monthly']['runs']:,} runs):")
-            output_parts.append(f"    Min: ${costs['estimated_monthly']['cost_min']:.2f}")
-            output_parts.append(f"    Max: ${costs['estimated_monthly']['cost_max']:.2f}")
+            monthly = costs['estimated_monthly']
+            output_parts.append(f"  Monthly ({monthly['runs']:,} runs): {monthly['tokens_min']:,} - {monthly['tokens_max']:,} tokens")
+            if 'cost_per_run' in costs:
+                output_parts.append(f"  Cost per run: ${costs['cost_per_run']['min']:.4f} - ${costs['cost_per_run']['max']:.4f}")
+                output_parts.append(f"  Monthly cost: ${monthly['cost_min']:.2f} - ${monthly['cost_max']:.2f}")
+            else:
+                output_parts.append("  Cost: pass --price-in and --price-out (USD per million tokens) to get dollars")
 
     # Output
     output = '\n'.join(output_parts)

package/skills/senior-prompt-engineer/scripts/prompt_optimizer.py

@@ -3,7 +3,7 @@
 Prompt Optimizer - Static analysis tool for prompt engineering
 
 Features:
-- Token estimation (GPT-4/Claude approximation)
+- Approximate token count (characters / 4, not a real tokenizer)
 - Prompt structure analysis
 - Clarity scoring
 - Few-shot example extraction and management
@@ -11,7 +11,7 @@ Features:
 
 Usage:
     python prompt_optimizer.py prompt.txt --analyze
-    python prompt_optimizer.py prompt.txt --tokens --model gpt-4
+    python prompt_optimizer.py prompt.txt --tokens
     python prompt_optimizer.py prompt.txt --optimize --output optimized.txt
     python prompt_optimizer.py prompt.txt --extract-examples --output examples.json
 """
@@ -25,32 +25,15 @@ from typing import Dict, List, Optional, Tuple
 from dataclasses import dataclass, asdict
 
 
-# Token estimation ratios (chars per token approximation)
-TOKEN_RATIOS = {
-    'gpt-4': 4.0,
-    'gpt-3.5': 4.0,
-    'claude': 3.5,
-    'default': 4.0
-}
-
-# Cost per 1K tokens (input)
-COST_PER_1K = {
-    'gpt-4': 0.03,
-    'gpt-4-turbo': 0.01,
-    'gpt-3.5-turbo': 0.0005,
-    'claude-3-opus': 0.015,
-    'claude-3-sonnet': 0.003,
-    'claude-3-haiku': 0.00025,
-    'default': 0.01
-}
+# Rough characters-per-token ratio. Real tokenizers differ by model and by text, so
+# every count here is an estimate; use the provider's token-counting API for exact numbers.
+CHARS_PER_TOKEN = 4.0
 
 
 @dataclass
 class PromptAnalysis:
     """Results of prompt analysis"""
     token_count: int
-    estimated_cost: float
-    model: str
     clarity_score: int
     structure_score: int
     issues: List[Dict[str, str]]
@@ -71,16 +54,9 @@ class FewShotExample:
     index: int
 
 
-def estimate_tokens(text: str, model: str = 'default') -> int:
-    """Estimate token count based on character ratio"""
-    ratio = TOKEN_RATIOS.get(model, TOKEN_RATIOS['default'])
-    return int(len(text) / ratio)
-
-
-def estimate_cost(token_count: int, model: str = 'default') -> float:
-    """Estimate cost based on token count"""
-    cost_per_1k = COST_PER_1K.get(model, COST_PER_1K['default'])
-    return round((token_count / 1000) * cost_per_1k, 6)
+def estimate_tokens(text: str) -> int:
+    """Approximate token count from the character count"""
+    return int(len(text) / CHARS_PER_TOKEN)
 
 
 def find_ambiguous_instructions(text: str) -> List[Dict[str, str]]:
@@ -89,11 +65,9 @@ def find_ambiguous_instructions(text: str) -> List[Dict[str, str]]:
 
     # Vague verbs that need specificity
     vague_patterns = [
-        (r'\b(analyze|process|handle|deal with)\b', 'Vague verb - specify the exact action'),
         (r'\b(good|nice|appropriate|suitable)\b', 'Subjective term - define specific criteria'),
         (r'\b(etc\.|and so on|and more)\b', 'Open-ended list - enumerate all items explicitly'),
         (r'\b(if needed|as necessary|when appropriate)\b', 'Conditional without criteria - specify when'),
-        (r'\b(some|several|many|few|various)\b', 'Vague quantity - use specific numbers'),
     ]
 
     lines = text.split('\n')
@@ -155,7 +129,7 @@ def check_output_format(text: str) -> Tuple[bool, List[str]]:
     has_format = any(re.search(p, text, re.IGNORECASE) for p in format_indicators)
 
     if not has_format:
-        suggestions.append('Add explicit output format specification (e.g., "Respond in JSON with keys: ...")')
+        suggestions.append('State the expected output format (structure, length, what to include)')
 
     return has_format, suggestions
 
@@ -277,7 +251,7 @@ def generate_suggestions(analysis: PromptAnalysis) -> List[str]:
     suggestions = []
 
     if not analysis.has_output_format:
-        suggestions.append('Add explicit output format: "Respond in JSON with keys: ..."')
+        suggestions.append('State the output format. If code will parse the response as JSON, enforce it with structured outputs instead of describing it in the prompt')
 
     if analysis.example_count == 0:
         suggestions.append('Consider adding 2-3 few-shot examples for consistent outputs')
@@ -289,22 +263,14 @@ def generate_suggestions(analysis: PromptAnalysis) -> List[str]:
     if analysis.clarity_score < 70:
         suggestions.append('Improve clarity: replace vague terms with specific instructions')
 
-    if analysis.token_count > 2000:
-        suggestions.append(f'Prompt is {analysis.token_count} tokens - consider condensing for cost efficiency')
-
-    # Check for role prompting
-    if not re.search(r'you are|act as|as a\s+\w+', analysis.sections[0].get('content', [''])[0] if analysis.sections else '', re.IGNORECASE):
-        suggestions.append('Consider adding role context: "You are an expert..."')
-
     return suggestions
 
 
-def analyze_prompt(text: str, model: str = 'gpt-4') -> PromptAnalysis:
+def analyze_prompt(text: str) -> PromptAnalysis:
     """Perform comprehensive prompt analysis"""
 
     # Basic metrics
-    token_count = estimate_tokens(text, model)
-    cost = estimate_cost(token_count, model)
+    token_count = estimate_tokens(text)
     word_count = len(text.split())
     line_count = len(text.split('\n'))
 
@@ -324,8 +290,6 @@ def analyze_prompt(text: str, model: str = 'gpt-4') -> PromptAnalysis:
 
     analysis = PromptAnalysis(
         token_count=token_count,
-        estimated_cost=cost,
-        model=model,
         clarity_score=clarity_score,
         structure_score=structure_score,
         issues=all_issues,
@@ -367,8 +331,7 @@ def format_report(analysis: PromptAnalysis) -> str:
     report.append("")
 
     report.append("📊 METRICS")
-    report.append(f"  Token count:     {analysis.token_count:,}")
-    report.append(f"  Estimated cost:  ${analysis.estimated_cost:.4f} ({analysis.model})")
+    report.append(f"  Tokens (approx): {analysis.token_count:,}")
     report.append(f"  Word count:      {analysis.word_count:,}")
     report.append(f"  Line count:      {analysis.line_count}")
     report.append("")
@@ -411,13 +374,16 @@ def format_report(analysis: PromptAnalysis) -> str:
 
 
 def main():
+    # The report uses emoji; a Windows console defaults to cp1252 and cannot print them.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
     parser = argparse.ArgumentParser(
         description="Prompt Optimizer - Analyze and optimize prompts",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
   %(prog)s prompt.txt --analyze
-  %(prog)s prompt.txt --tokens --model claude-3-sonnet
+  %(prog)s prompt.txt --tokens
   %(prog)s prompt.txt --optimize --output optimized.txt
   %(prog)s prompt.txt --extract-examples --output examples.json
         """
@@ -428,9 +394,6 @@ Examples:
     parser.add_argument('--tokens', '-t', action='store_true', help='Count tokens only')
     parser.add_argument('--optimize', '-O', action='store_true', help='Generate optimized version')
     parser.add_argument('--extract-examples', '-e', action='store_true', help='Extract few-shot examples')
-    parser.add_argument('--model', '-m', default='gpt-4',
-                       choices=['gpt-4', 'gpt-4-turbo', 'gpt-3.5-turbo', 'claude-3-opus', 'claude-3-sonnet', 'claude-3-haiku'],
-                       help='Model for token/cost estimation')
     parser.add_argument('--output', '-o', help='Output file path')
     parser.add_argument('--json', '-j', action='store_true', help='Output as JSON')
     parser.add_argument('--compare', '-c', help='Compare with baseline analysis JSON')
@@ -447,17 +410,11 @@ Examples:
 
     # Tokens only
     if args.tokens:
-        token_count = estimate_tokens(text, args.model)
-        cost = estimate_cost(token_count, args.model)
+        token_count = estimate_tokens(text)
         if args.json:
-            print(json.dumps({
-                'tokens': token_count,
-                'cost': cost,
-                'model': args.model
-            }, indent=2))
+            print(json.dumps({'tokens_approx': token_count}, indent=2))
         else:
-            print(f"Tokens: {token_count:,}")
-            print(f"Estimated cost: ${cost:.4f} ({args.model})")
+            print(f"Tokens (approx): {token_count:,}")
         sys.exit(0)
 
     # Extract examples
@@ -481,8 +438,8 @@ Examples:
             print(f"Optimized prompt written to {args.output}")
 
             # Show comparison
-            orig_tokens = estimate_tokens(text, args.model)
-            new_tokens = estimate_tokens(optimized, args.model)
+            orig_tokens = estimate_tokens(text)
+            new_tokens = estimate_tokens(optimized)
             saved = orig_tokens - new_tokens
             print(f"Tokens: {orig_tokens:,} -> {new_tokens:,} (saved {saved:,})")
         else:
@@ -490,7 +447,7 @@ Examples:
         sys.exit(0)
 
     # Default: full analysis
-    analysis = analyze_prompt(text, args.model)
+    analysis = analyze_prompt(text)
 
     # Compare with baseline
     if args.compare:

package/skills/shader-dev/reference/fluid-simulation.md

@@ -180,7 +180,7 @@ if (p.x < 1.0 || p.y < 1.0 ||
     c.xyw *= 0.0;
 }
 
-// IMPORTANT: Ink decay: must use multiplicative decay; subtractive decay causes saturation in high-concentration areas and overly fast decay in low-concentration areas
+// Ink decay: must use multiplicative decay; subtractive decay causes saturation in high-concentration areas and overly fast decay in low-concentration areas
 c.w *= 0.995;  // 0.5% decay per frame, adjustable [0.99=fast dissipation, 0.999=persistent]
 
 // Numerical clamping (prevent explosion)
@@ -199,14 +199,14 @@ void mainImage(out vec4 fragColor, in vec2 fragCoord) {
     vec2 uv = fragCoord / iResolution.xy;
     vec4 c = texture(iChannel0, uv);
 
-    // IMPORTANT: Color base must be bright enough! 0.5+0.5*cos produces bright colors in [0,1] range
+    // Color base must be bright enough! 0.5+0.5*cos produces bright colors in [0,1] range
     // Never use extremely dark base colors like vec3(0.02, 0.01, 0.08) — multiplied by ink, they become invisible
     vec3 col = 0.5 + 0.5 * cos(atan(c.y, c.x) + vec3(0.0, 2.1, 4.2));
-    // IMPORTANT: Use smoothstep instead of linear division to preserve gradient variation
+    // Use smoothstep instead of linear division to preserve gradient variation
     float ink = smoothstep(0.0, 2.0, c.w);
     col *= ink;
 
-    // IMPORTANT: Background color must be visible to the eye (RGB at least > 5/255 ≈ 0.02), otherwise users think the page is all black
+    // Background color must be visible to the eye (RGB at least > 5/255 ≈ 0.02), otherwise users think the page is all black
     col = max(col, vec3(0.02, 0.012, 0.035));
 
     fragColor = vec4(col, 1.0);

package/skills/shader-dev/reference/simulation-physics.md

@@ -50,12 +50,12 @@ Numerical viscosity over-smooths small-scale vortices. Vorticity confinement com
 
 **Why**: GPU shaders cannot simultaneously read and write the same buffer. The ping-pong strategy reads from one buffer (previous frame's data) and writes to the other each frame, then swaps on the next frame.
 
-**IMPORTANT: Key Difference Between ShaderToy and WebGL2**: In ShaderToy, Buffer A/B are two independent passes with separate write targets, so `iChannel0=self, iChannel1=other` doesn't conflict. However, in WebGL2 there's only one shader program doing ping-pong, and the write target texture cannot be simultaneously read. The solution is **dual-channel encoding** (R=current height, G=previous frame height).
+**Key Difference Between ShaderToy and WebGL2**: In ShaderToy, Buffer A/B are two independent passes with separate write targets, so `iChannel0=self, iChannel1=other` doesn't conflict. However, in WebGL2 there's only one shader program doing ping-pong, and the write target texture cannot be simultaneously read. The solution is **dual-channel encoding** (R=current height, G=previous frame height).
 
 **Code** (WebGL2-safe version, reads only from iChannel0, with RGBA8-compatible encoding):
 ```glsl
-// IMPORTANT: Only use iChannel0 (read currentBuf), write to nextBuf (must be different!)
-// IMPORTANT: encode/decode ensure signed values aren't clipped on RGBA8 (no float textures/SwiftShader)
+// Only use iChannel0 (read currentBuf), write to nextBuf (must be different!)
+// encode/decode ensure signed values aren't clipped on RGBA8 (no float textures/SwiftShader)
 uniform int useFloatTex;
 float decode(float v) { return useFloatTex == 1 ? v : v * 2.0 - 1.0; }
 float encode(float v) { return useFloatTex == 1 ? v : v * 0.5 + 0.5; }
@@ -244,7 +244,7 @@ void mainImage(out vec4 fragColor, in vec2 fragCoord)
 #define SIZY 64.0   // adjustable: cloth height (particle count)
 
 // Left half [0, SIZX) stores positions, right half [SIZX, 2*SIZX) stores velocities
-// IMPORTANT: In WebGL2, getpos/getvel both read from iChannel0 (currentBuf, read-only),
+// In WebGL2, getpos/getvel both read from iChannel0 (currentBuf, read-only),
 //    write target is nextBuf (separate buffer), avoiding read-write conflict
 vec3 getpos(vec2 id)
 {
@@ -298,7 +298,7 @@ void edge(vec2 dif)
     vec3 posdif = getpos(dif + c) - pos;
     vec3 veldif = getvel(dif + c) - ovel;
 
-    // IMPORTANT: Must check for zero length, otherwise normalize(vec3(0)) produces NaN
+    // Must check for zero length, otherwise normalize(vec3(0)) produces NaN
     float plen = length(posdif);
     if (plen < 0.0001) return;
     vec3 dir = posdif / plen;
@@ -498,7 +498,7 @@ if (length(pos - ballPos) < ballRadius) {
 }
 ```
 
-> **IMPORTANT: Common Pitfalls**:
+> **Common Pitfalls**:
 > - **Cloth Image Pass must project world coordinates to screen**: You cannot use `uv * vec2(SIZX, SIZY)` to map screen UV to grid ID, because particles have moved from their initial positions, producing scattered fragments. You must iterate over mesh faces, projecting vertex world coordinates to screen space for triangle rasterization
 > - GLSL is strictly typed; you cannot write `float / vec2`. Wrong example: `length(dif) / vec2(SIZX, SIZY).x` will first execute float/vec2 causing a compile error; use `length(dif) / SIZX` instead
 > - `normalize(vec3(0))` produces NaN; all `normalize()` calls must include a length check beforehand

package/skills/shader-dev/reference/voxel-rendering.md

@@ -619,7 +619,7 @@ A complete voxel water scene with surface wave reflections, underwater refractio
 float waterY = 0.0;
 
 // Underwater voxel scene (sand + seaweed)
-// IMPORTANT: c.xz returns vec2, which only has .x/.y components — never use .z!
+// c.xz returns vec2, which only has .x/.y components — never use .z!
 int getVoxel(vec3 c) {
     float sandHeight = -3.0 + 0.5 * sin(c.x * 0.3) * cos(c.z * 0.4);
     if (c.y < sandHeight) return 1;      // Sand interior

package/skills/shader-dev/techniques/ambient-occlusion.md

@@ -1,6 +1,6 @@
 ## WebGL2 Adaptation Requirements
 
-**IMPORTANT: GLSL Type Strictness**: float and vec types cannot be implicitly converted. `vec3 v = 1.0;` is illegal; you must use the vector form (e.g., `vec3(1.0)`, `vec3(1.0) * x`, `value * vec3(1.0)`).
+**GLSL Type Strictness**: float and vec types cannot be implicitly converted. `vec3 v = 1.0;` is illegal; you must use the vector form (e.g., `vec3(1.0)`, `vec3(1.0) * x`, `value * vec3(1.0)`).
 
 The code templates in this document use ShaderToy GLSL style. When generating standalone HTML pages, you must adapt for WebGL2:
 

package/skills/shader-dev/techniques/analytic-ray-tracing.md

@@ -193,7 +193,7 @@ vec3 shade(vec3 pos, vec3 normal, vec3 rd, vec3 albedo) {
 }
 ```
 
-> **IMPORTANT: Critical pitfall**: `d.xy` must be passed as distBound, and `d.y` must be updated each time a closer intersection is found! If the deployed code passes the original `dist` directly without updating, the intersection logic will fail (all object distance tests become invalid), resulting in a completely black screen.
+> **Critical pitfall**: `d.xy` must be passed as distBound, and `d.y` must be updated each time a closer intersection is found! If the deployed code passes the original `dist` directly without updating, the intersection logic will fail (all object distance tests become invalid), resulting in a completely black screen.
 
 ```glsl
 #define MAX_BOUNCES 4
@@ -229,7 +229,7 @@ vec3 radiance(vec3 ro, vec3 rd) {
 
 Runs directly on ShaderToy, includes sphere, plane, and box primitives with reflection and Blinn-Phong shading.
 
-> **IMPORTANT: Must follow**: All intersection function calls must use `d.xy` as the `distBound` parameter, and update `d.y` after each closer intersection is found. Incorrect usage: `iSphere(ro, rd, dist, ...)` (always using the original dist). Correct usage: `iSphere(ro, rd, d.xy, ...)` followed by `if (t < d.y) { d.y = t; ... }` to update.
+> **Must follow**: All intersection function calls must use `d.xy` as the `distBound` parameter, and update `d.y` after each closer intersection is found. Incorrect usage: `iSphere(ro, rd, dist, ...)` (always using the original dist). Correct usage: `iSphere(ro, rd, d.xy, ...)` followed by `if (t < d.y) { d.y = t; ... }` to update.
 
 ```glsl
 // Analytic Ray Tracing - Complete ShaderToy Template

package/skills/shader-dev/techniques/domain-warping.md

@@ -117,8 +117,8 @@ float fbm(vec2 p) {
 
 ```glsl
 // Map scalar field (0~1) to color using a mix chain
-// IMPORTANT: Note: GLSL is strictly typed. Variable declarations must be complete, e.g. vec3 col = vec3(0.2, 0.1, 0.4)
-// IMPORTANT: Decimals must be written as 0.x, not .x (division by zero errors)
+// GLSL is strictly typed. Variable declarations must be complete, e.g. vec3 col = vec3(0.2, 0.1, 0.4)
+// Decimals must be written as 0.x, not .x (division by zero errors)
 vec3 palette(float t) {
     vec3 col = vec3(0.2, 0.1, 0.4);                               // deep purple base
     col = mix(col, vec3(0.3, 0.05, 0.05), t);                     // dark red