aiox-core 5.0.7 → 5.0.8

package/.claude/skills/tech-search/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: tech-search
+description: |
+  Self-contained deep tech research. WebSearch + WebFetch + Haiku workers.
+  Pipeline: Query > Decompose > Parallel Search (Haiku) > Evaluate > Synthesize > Document.
+  Zero external dependencies. MCPs optional.
+  Salva em docs/research/{YYYY-MM-DD}-{slug}/.
+---
+
+# Tech Search
+
+Self-contained deep research pipeline. Zero external dependencies.
+
+## Quick Start
+
+```
+/tech-search "React Server Components vs Client Components"
+```
+
+## Activation
+
+1. Parse query from `$ARGUMENTS` (or ask if not provided)
+2. Execute 6-phase workflow
+3. Save to `docs/research/{YYYY-MM-DD}-{slug}/`
+
+**CRITICAL:**
+- NEVER implement code. Redirect to @pm or @dev.
+- NEVER write files outside `docs/research/`.
+
+---
+
+## SKILL DEFINITION
+
+```yaml
+skill:
+  name: Tech Search
+  id: tech-search
+
+veto_conditions:
+  - id: VETO_NO_RESULTS
+    trigger: "ALL search waves return 0 results"
+    action: "STOP + Report: 'No results found. Reformulate query or check connectivity.'"
+
+  - id: VETO_IMPLEMENTATION_REQUEST
+    trigger: "User asks to implement, code, create agent/skill, or deploy"
+    action: "REDIRECT: 'Implementation is not my scope. Use @pm for prioritization or @dev for execution.'"
+    keywords:
+      - "implementa"
+      - "cria o agent"
+      - "cria a skill"
+      - "faz o codigo"
+      - "escreve o codigo"
+      - "desenvolve"
+      - "deploy"
+      - "implement"
+      - "build this"
+      - "code this"
+
+  - id: VETO_FORBIDDEN_PATH
+    trigger: "Attempt to write outside docs/research/"
+    action: "BLOCK + Error: 'Writing outside docs/research/ is forbidden.'"
+
+constraints:
+  forbidden_actions:
+    - NEVER implement code, agents, skills, or production artifacts
+    - NEVER create files outside docs/research/
+    - NEVER write to .claude/agents/, .claude/skills/, squads/, app/, lib/
+
+tool_hierarchy:
+  search:
+    1_preferred: "Exa MCP (mcp__exa__web_search_exa) - if available"
+    2_fallback: "WebSearch (always available)"
+    detection: "Try Exa first. If 401/429/503, set exa_available=false, use WebSearch."
+
+  docs:
+    1_preferred: "Context7 MCP (mcp__context7__resolve-library-id + query-docs) - if available"
+    2_fallback: "WebSearch with 'site:{library}.dev docs' or 'site:{library}.io docs'"
+    detection: "Try Context7 first. If fails, set context7_available=false."
+
+  deep_read:
+    only: "WebFetch with prompts/page-extract.md prompt"
+    note: "No ETL, no Bash, no external scripts. Pure WebFetch."
+
+  workers:
+    type: "general-purpose"
+    model: "haiku"
+    max_parallel: 5
+    max_deep_reads_per_worker: 3
+
+workflow:
+  phases:
+
+    # ──────────────────────────────────────────────
+    # PHASE 1: AUTO-CLARIFY
+    # ──────────────────────────────────────────────
+    1_auto_clarify:
+      name: "Auto-Clarification"
+      model_tier: "MAIN MODEL (inline)"
+      description: |
+        Pattern matching + technology detection on the user query.
+        Determines if clarification is needed or can be skipped.
+
+      execution: |
+        1. Read user query (original text, unmodified)
+
+        2. PATTERN MATCHING (case-insensitive):
+           - Technical keywords: "code", "implement", "how to", "api", "bug",
+             "error", "debug", "library", "sdk", "tutorial", "example"
+             → inferred_context.focus = "technical"
+           - Comparison keywords: "compare", "vs", "versus", "difference",
+             "better", "alternative", "tradeoff", "pros and cons"
+             → inferred_context.focus = "comparison"
+           - Recency keywords: "latest", "new", "2024", "2025", "2026",
+             "recent", "state of the art", "trending"
+             → inferred_context.temporal = "recent"
+             → Append current year to search queries
+
+        3. TECHNOLOGY DETECTION (case-insensitive):
+           Scan for known technologies:
+           - Languages: JavaScript/JS, TypeScript/TS, Python, Java, Go, Rust, C#, Ruby, PHP
+           - Frameworks: React, Next.js, Vue, Angular, Svelte, Express, FastAPI, Django, Flask
+           - Databases: PostgreSQL, MySQL, MongoDB, Redis, Supabase, Firebase, Elasticsearch
+           - AI/ML: LLM, RAG, LangChain, OpenAI, Claude, Anthropic, TensorFlow, PyTorch
+           - Infra: Docker, Kubernetes, AWS, Vercel, GraphQL, REST, WebSocket
+           → Collect into inferred_context.domain = [list]
+
+        4. DECISION:
+           - IF any pattern OR technology detected → skip clarification
+           - IF nothing detected → ask ONE question:
+             "Your query seems broad. What is the focus and technical context?"
+
+      output: "inferred_context object {focus, temporal, domain, skip_clarification}"
+
+    # ──────────────────────────────────────────────
+    # PHASE 2: DECOMPOSE
+    # ──────────────────────────────────────────────
+    2_decompose:
+      name: "Query Decomposition"
+      model_tier: "MAIN MODEL"
+      description: |
+        Decomposes user query into 5-7 atomic, directly searchable sub-queries.
+        Uses extended thinking for deeper analysis.
+
+      execution: |
+        ultrathink
+
+        1. DEEP ANALYSIS (use extended thinking):
+           - What are the REAL questions behind this query?
+           - What would a domain expert want to know?
+           - What gaps might standard searches miss?
+           - What assumptions should be tested?
+
+        2. GENERATE 5-7 sub-queries that:
+           - Cover ORTHOGONAL angles (not overlapping)
+           - Include at least one "devil's advocate" query
+           - Include at least one "expert-level" query
+           - Are directly searchable (not abstract)
+
+        3. INCORPORATE inferred_context:
+           - If focus=comparison → ensure queries cover both/all sides
+           - If temporal=recent → add year constraints
+           - If domain detected → scope queries to those technologies
+
+        4. OUTPUT format:
+           {
+             "main_topic": "string",
+             "sub_queries": ["query1", "query2", ...],
+             "search_strategy": "parallel"
+           }
+
+      output: "decomposition_result JSON"
+
+    # ──────────────────────────────────────────────
+    # PHASE 3: PARALLEL SEARCH (Haiku Workers)
+    # ──────────────────────────────────────────────
+    3_parallel_search:
+      name: "Parallel Search via Haiku Workers"
+      model_tier: "HAIKU (via Task tool, general-purpose agent)"
+      description: |
+        Dispatches sub-queries as parallel Haiku workers.
+        Each worker: WebSearch → select top URLs → WebFetch on best → return JSON.
+        Max 5 workers in parallel. No external dependencies.
+
+      execution: |
+        1. PRE-CHECK MCP AVAILABILITY (main model, before dispatch):
+           - Try Context7: mcp__context7__resolve-library-id for detected library
+             → If fails: context7_available = false
+           - Try Exa: mcp__exa__web_search_exa("test", 1)
+             → If 401/429/503: exa_available = false
+
+        2. DISPATCH WORKERS:
+           For EACH sub-query, create a Task call:
+
+           Task(
+             subagent_type: "general-purpose",
+             model: "haiku",
+             prompt: <WORKER_PROMPT>
+           )
+
+           Dispatch ALL Task calls in a SINGLE message for parallel execution.
+           Max 5 workers.
+
+           WORKER PROMPT TEMPLATE:
+           ```
+           You are a research worker. Search and extract information for ONE specific query.
+
+           QUERY: {sub_query}
+           CONTEXT: {inferred_context_json}
+           MCP AVAILABILITY: exa={exa_available}, context7={context7_available}
+
+           INSTRUCTIONS:
+           1. Search using the best available tool:
+              - If context7 available AND query is about a specific library:
+                → Use mcp__context7__resolve-library-id then mcp__context7__query-docs
+              - If exa available:
+                → Use mcp__exa__web_search_exa(query, numResults=5)
+              - Else:
+                → Use WebSearch(query)
+
+           2. From search results, select top 2-3 most relevant URLs
+
+           3. Deep-read top 1-3 results using WebFetch:
+              - For each URL, use WebFetch with this prompt:
+                "Extract technical information relevant to: {sub_query}
+                 Focus on: specific facts/numbers/benchmarks, code examples (preserve exactly),
+                 best practices and warnings, expert recommendations.
+                 Skip: navigation, ads, generic intros.
+                 Format as structured markdown with Key Findings, Code/Examples,
+                 Expert Quotes, and Actionable Insights sections."
+
+           4. Return results as JSON (no other text):
+              {
+                "sub_query": "the original sub-query",
+                "sources": [
+                  {"url": "...", "title": "...", "snippet": "first 200 chars...",
+                   "credibility": "HIGH|MEDIUM|LOW", "tool_used": "WebSearch|Exa|Context7"}
+                ],
+                "key_findings": ["finding1 with specific data", "finding2", ...],
+                "code_examples": ["```lang\ncode\n```", ...],
+                "expert_quotes": ["quote — author", ...]
+              }
+
+           IMPORTANT:
+           - Do NOT synthesize or write reports. Just search and return raw findings.
+           - Be HONEST about credibility (LOW if source is generic/outdated).
+           - Preserve code examples EXACTLY as found.
+           - Max 3 deep reads per worker.
+           ```
+
+        3. AGGREGATE RESULTS (main model):
+           - Collect all worker responses
+           - Parse JSON from each Task result
+           - Deduplicate by URL (keep highest credibility)
+           - Build unified results with tool attribution
+
+        4. HANDLE FAILURES:
+           - For failed workers (no response or invalid JSON):
+             → Log warning, execute that sub-query directly in main context
+           - RULE: at least 1 successful result to proceed
+
+      output: |
+        {
+          "search_results": [...],
+          "tools_used": {"exa": N, "context7": N, "websearch": N, "webfetch": N},
+          "worker_stats": {"dispatched": N, "succeeded": N, "failed": N}
+        }
+
+    # ──────────────────────────────────────────────
+    # PHASE 4: EVALUATE COVERAGE
+    # ──────────────────────────────────────────────
+    4_evaluate_coverage:
+      name: "Coverage Evaluation"
+      model_tier: "HAIKU (via Task tool)"
+      description: |
+        Evaluates if research is complete. Decides CONTINUE or STOP.
+        Max 2 waves total (simpler than tech-research's 3 waves).
+
+      execution: |
+        Wrap in Task(model: "haiku"):
+
+        1. Calculate metrics:
+           - coverage_score (0-100): How well do findings answer the original query?
+           - source_quality: Count HIGH/MEDIUM/LOW credibility sources
+           - new_info_ratio: Estimate unique facts vs total
+
+        2. STOPPING RULES:
+           HARD STOPS (always stop):
+           - wave >= 2 → "Max iterations reached"
+           - coverage_score >= 80 AND high_credibility >= 3 → "Sufficient coverage"
+
+           SOFT STOP:
+           - coverage_score >= 65 AND wave >= 1 → "Acceptable coverage"
+
+           MUST CONTINUE:
+           - coverage_score < 50 AND wave == 1 → "Insufficient first wave"
+
+        3. IF CONTINUE:
+           - Generate 2-3 targeted gap-filling queries
+           - Return to Phase 3 (search again with new queries)
+
+        4. IF STOP:
+           - Document final score and remaining gaps
+
+      output: |
+        {
+          "decision": "CONTINUE|STOP",
+          "coverage_score": 0-100,
+          "stop_reason": "reason",
+          "gaps": [...],
+          "next_queries": [...] (if CONTINUE)
+        }
+
+    # ──────────────────────────────────────────────
+    # PHASE 5: SYNTHESIZE
+    # ──────────────────────────────────────────────
+    5_synthesize:
+      name: "Synthesize"
+      model_tier: "MAIN MODEL"
+      description: |
+        Consolidates all findings into a comprehensive research report.
+        Produces DOCUMENTATION ONLY, never production code.
+
+      execution: |
+        1. Review all aggregated search results and findings
+        2. Identify patterns, consensus, and contradictions across sources
+        3. Rank techniques/solutions by evidence strength
+        4. Generate:
+           - Executive summary (TL;DR)
+           - Detailed findings organized by theme
+           - Code examples for REFERENCE only (not production)
+           - Decision matrix: when to use what
+           - Practical next steps recommending @pm or @dev
+        5. ALWAYS end with "Next Steps" section redirecting to implementation agents
+
+      output: "Synthesized report content"
+
+    # ──────────────────────────────────────────────
+    # PHASE 6: DOCUMENT
+    # ──────────────────────────────────────────────
+    6_document:
+      name: "Document"
+      model_tier: "MAIN MODEL"
+      description: "Save complete research to docs/research/"
+      structure:
+        folder: "docs/research/{YYYY-MM-DD}-{slug}/"
+        files:
+          - name: "README.md"
+            content: "Index + TL;DR"
+          - name: "00-query-original.md"
+            content: "Original question + inferred context"
+          - name: "01-deep-research-prompt.md"
+            content: "Generated structured prompt with sub-queries"
+          - name: "02-research-report.md"
+            content: "Complete research findings"
+          - name: "03-recommendations.md"
+            content: "Recommendations and next steps (NO production code)"
+
+security:
+  - Never include API keys or secrets in research docs
+  - Sanitize sensitive paths before saving
+  - Validate URLs before fetching
+  - NEVER write files outside docs/research/
+  - NEVER create agents, skills, or production code
+
+scope_boundaries:
+  allowed_paths:
+    - "docs/research/**"
+  forbidden_paths:
+    - ".claude/agents/"
+    - ".claude/skills/"
+    - "squads/"
+    - "app/"
+    - "lib/"
+    - "src/"
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.py"
+  exception: "Code examples within docs/research/ markdown are allowed for DOCUMENTATION only"
+```
+
+---
+
+## Execution Flow
+
+```
+Query → Auto-Clarify → Decompose (ultrathink, MAIN MODEL)
+                              |
+              [Sub-query 1]  [Sub-query 2]  ... [Sub-query 5]
+                   |              |                   |
+              [Haiku GP]     [Haiku GP]          [Haiku GP]
+              (search+read)  (search+read)       (search+read)
+                   |              |                   |
+                   +------+-------+-------+-----------+
+                          |
+                    Aggregate (MAIN MODEL)
+                          |
+                    Evaluate Coverage (HAIKU)
+                          |
+                    (coverage OK?) ── NO ──→ [Wave 2, max 2 total]
+                          | YES
+                          |
+                    Synthesize (MAIN MODEL)
+                          |
+                    Document (MAIN MODEL)
+```
+
+## What This Skill Does NOT Have
+
+- No ETL service dependency
+- No infrastructure/ references
+- No squads/ references
+- No Bash commands
+- No custom agents (uses built-in general-purpose)
+- No Python/JS scripts
+- No npm dependencies
+- No wave compression (max 2 waves, context is sufficient)
+- No citation verification (simplifies without quality loss)
+- No follow-up behavior (run again for more research)
+- No BlogDiscovery or SemanticChunker
+
+## Output Structure
+
+```
+docs/research/{YYYY-MM-DD}-{slug}/
+├── README.md                    # Index + TL;DR
+├── 00-query-original.md         # Original question + context
+├── 01-deep-research-prompt.md   # Generated prompt with sub-queries
+├── 02-research-report.md        # Complete findings
+└── 03-recommendations.md        # Recommendations (NO production code)
+```

package/.claude/skills/tech-search/prompts/page-extract.md

@@ -0,0 +1,133 @@
+## ROLE
+Technical content extractor. Simulates Exa's content extraction when reading pages.
+
+## TASK
+Extract structured, relevant information from the page at {{URL}} related to: {{QUERY}}
+
+## EXTRACTION RULES
+
+### What to Extract
+
+1. **Key Facts** - Concrete information, numbers, specifications
+2. **Code Examples** - Actual code snippets (not just mentions)
+3. **Process/Steps** - How-to instructions, workflows
+4. **Comparisons** - Pros/cons, tradeoffs, benchmarks
+5. **Expert Opinions** - Quotes, recommendations from authors
+6. **Warnings/Gotchas** - Common mistakes, anti-patterns
+
+### What to SKIP
+
+- Navigation, headers, footers
+- Ads, promotional content
+- Generic introductions ("In this article we will...")
+- Redundant content already covered
+- Author bios (unless relevant)
+
+## OUTPUT FORMAT
+
+```markdown
+## Source: {{TITLE}}
+URL: {{URL}}
+Relevance: HIGH|MEDIUM|LOW
+
+### Key Findings
+- {Finding 1 with specific data}
+- {Finding 2 with specific data}
+
+### Code/Examples
+```{language}
+{actual code from the page}
+```
+
+### Expert Quote
+> "{direct quote}" — {author if known}
+
+### Actionable Insights
+1. {What to do based on this source}
+2. {What to avoid}
+
+### Cross-Reference Notes
+- Confirms: {what other sources said}
+- Contradicts: {what differs from other sources}
+- Adds: {new information not found elsewhere}
+```
+
+## QUALITY GATES
+
+Before returning, verify:
+- [ ] At least 3 key findings extracted
+- [ ] Specific data (numbers, versions, dates) included when available
+- [ ] Code examples preserved exactly (not paraphrased)
+- [ ] Relevance score is honest (LOW if page didn't help)
+
+## EXAMPLES
+
+### Good Extraction
+
+```markdown
+## Source: Redis Caching Best Practices for Node.js
+URL: https://example.com/redis-node-best-practices
+Relevance: HIGH
+
+### Key Findings
+- Redis connection pooling reduces latency by 40% in high-traffic apps
+- Default TTL of 3600s is recommended for session data
+- Use `SCAN` instead of `KEYS` in production (KEYS blocks)
+
+### Code/Examples
+```javascript
+const redis = require('redis');
+const client = redis.createClient({
+  socket: { connectTimeout: 5000 },
+  retry_strategy: (options) => Math.min(options.attempt * 100, 3000)
+});
+```
+
+### Expert Quote
+> "Always set memory limits with maxmemory-policy allkeys-lru to prevent OOM kills" — Redis Labs documentation
+
+### Actionable Insights
+1. Implement connection pooling with 10-20 connections per instance
+2. Never use KEYS command in production loops
+
+### Cross-Reference Notes
+- Confirms: TTL importance (also mentioned in Stack Overflow thread)
+- Adds: Specific memory policy recommendation (new info)
+```
+
+### Honest LOW Relevance
+
+```markdown
+## Source: Introduction to Caching Concepts
+URL: https://example.com/caching-101
+Relevance: LOW
+
+### Key Findings
+- Basic explanation of what caching is (generic)
+- No Node.js specific content
+- No code examples
+
+### Actionable Insights
+1. Skip this source for implementation details
+
+### Cross-Reference Notes
+- Adds: Nothing new, basic tutorial level
+```
+
+## EXECUTION
+
+When using WebFetch, pass this as the prompt:
+
+```
+Extract technical information relevant to: {original query}
+
+Focus on:
+1. Specific facts, numbers, benchmarks
+2. Code examples (preserve exactly)
+3. Best practices and warnings
+4. Expert recommendations
+
+Skip: navigation, ads, generic intros.
+
+Format as structured markdown with Key Findings, Code Examples, Expert Quotes, and Actionable Insights sections.
+```

package/README.en.md

@@ -602,14 +602,14 @@ Squads are modular AI agent teams. See the [Squads Overview](docs/guides/squads-
 
 ## AIOX Pro
 
-**AIOX Pro** (`@aiox-fullstack/pro`) is the premium module of AIOX, offering advanced features for teams and larger-scale projects.
+**AIOX Pro** is the premium module of AIOX, offering advanced features for teams and larger-scale projects.
 
 > **Restricted availability:** AIOX Pro is available exclusively to members of the **AIOX Cohort Advanced**. [Learn more about the program](https://aioxsquad.ai).
 
 ### Installation
 
 ```bash
-npm install @aiox-fullstack/pro
+npx aiox-pro install
 ```
 
 ### Premium Features

package/README.md

@@ -604,16 +604,22 @@ Squads são equipes modulares de agentes IA. Veja a [Visão Geral de Squads](doc
 
 ## AIOX Pro
 
-O **AIOX Pro** (`@aiox-fullstack/pro`) é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.
+O **AIOX Pro** é o módulo premium do AIOX, oferecendo funcionalidades avançadas para equipes e projetos de maior escala.
 
 > **Disponibilidade restrita:** O AIOX Pro está disponível exclusivamente para membros do **AIOX Cohort Advanced**. [Saiba mais sobre o programa](https://aioxsquad.ai).
 
 ### Instalação
 
 ```bash
-npm install @aiox-fullstack/pro
+npx aiox-pro install
 ```
 
+### Identificação Estável de Máquina (>= 5.0.8)
+
+O AIOX Pro agora usa o UUID nativo do sistema operacional para gerar `machineId`, preservando o hash SHA-256 e evitando consumo extra de assentos quando o macOS, VPNs ou redes Wi-Fi alteram o MAC/interface ativa.
+
+Caches locais de licença criados pelo algoritmo antigo são migrados automaticamente na próxima leitura. A janela de fallback legacy é de 90 dias; depois disso, instalações antigas precisam reativar online.
+
 ### Features Premium
 
 - **Squads Avançados** - Squads especializados com capacidades expandidas