@ornexus/neocortex 4.0.1 → 4.0.2

package/packages/client/dist/tier/tier-aware-client.js

@@ -1,260 +1 @@
-/**
- * @license FSL-1.1
- * Copyright (c) 2026 OrNexus AI
- *
- * This file is part of Neocortex CLI, licensed under the
- * Functional Source License, Version 1.1 (FSL-1.1).
- *
- * Change Date: February 20, 2029
- * Change License: MIT
- *
- * See the LICENSE file in the project root for full license text.
- */
-// ── Constants ────────────────────────────────────────────────────────────
-const TIER_CACHE_KEY = 'neocortex:tier';
-const QUOTA_CACHE_KEY_PREFIX = 'neocortex:quota:';
-const QUOTA_TTL_MS = 5 * 60 * 1000; // 5 minutes
-const TIER_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour (Story 31.05: reduced from 24h to align with short-lived JWTs)
-const VALID_TIERS = new Set(['free', 'pro', 'enterprise']);
-const DEFAULT_TIER = 'free';
-// ── Trigger Gates (inlined from shared tier-config to avoid import issues) ─
-const TRIGGER_GATES = {
-    'status': 'free',
-    'init': 'free',
-    'create-epic': 'free',
-    'idea-diagnose': 'free',
-    'idea-research': 'free',
-    'generate-epic': 'free',
-    'exec': 'pro',
-    'yolo': 'pro',
-    'epic': 'pro',
-    'setup-branch': 'free',
-    'diagnose': 'free',
-    'research': 'free',
-    'write-spec': 'free',
-    'create-tasks': 'free',
-    'implement': 'free',
-    'update-memory': 'free',
-    'commit': 'free',
-    'sync': 'free',
-    'create-pr': 'free',
-    'review': 'pro',
-    'merge': 'free',
-    'fix-blocked': 'free',
-    'finalize-epic': 'free',
-    'cleanup': 'free',
-    'resolve-conflicts': 'free',
-    'audit': 'free',
-    'menu': 'free',
-    'plans': 'free',
-    'billing': 'free',
-    'subscribe': 'free',
-};
-const TIER_HIERARCHY = {
-    free: 0,
-    pro: 1,
-    enterprise: 2,
-};
-// ── TierAwareClient ──────────────────────────────────────────────────────
-export class TierAwareClient {
-    cache;
-    licenseClient;
-    cachedTier = null;
-    constructor(options) {
-        this.cache = options.cacheProvider;
-        this.licenseClient = options.licenseClient;
-    }
-    // ── Story 60.1: Tier Extraction from JWT + Cache ────────────────────
-    /**
-     * Get the current tier. Checks in-memory, then cache, then JWT token.
-     * NEVER throws - returns 'free' on failure (fail-open).
-     */
-    async getCachedTier() {
-        try {
-            // 1. In-memory
-            if (this.cachedTier)
-                return this.cachedTier;
-            // 2. EncryptedCache
-            const cached = await this.cache.get(TIER_CACHE_KEY);
-            if (cached && VALID_TIERS.has(cached)) {
-                this.cachedTier = cached;
-                return this.cachedTier;
-            }
-            // 3. Extract from JWT
-            const token = await this.licenseClient.getToken();
-            if (token) {
-                const tier = this.extractTierFromJwt(token);
-                this.cachedTier = tier;
-                // Persist to cache (fire-and-forget)
-                this.cache.set(TIER_CACHE_KEY, tier, TIER_CACHE_TTL_MS).catch(() => { });
-                return tier;
-            }
-            return DEFAULT_TIER;
-        }
-        catch {
-            return DEFAULT_TIER;
-        }
-    }
-    /**
-     * Update cached tier (called when server returns tier info).
-     */
-    async updateTier(tier) {
-        try {
-            if (!VALID_TIERS.has(tier))
-                return;
-            this.cachedTier = tier;
-            await this.cache.set(TIER_CACHE_KEY, tier, TIER_CACHE_TTL_MS).catch(() => { });
-        }
-        catch {
-            // Non-critical
-        }
-    }
-    // ── Story 18.8: Tier Cache Invalidation ──────────────────────────────
-    /**
-     * Invalidate all tier and quota caches.
-     * Called when a tier change is detected to ensure fresh data.
-     * NEVER throws.
-     */
-    async invalidateTierCache() {
-        try {
-            this.cachedTier = null;
-            await this.cache.clear().catch(() => { });
-        }
-        catch {
-            // Non-critical
-        }
-    }
-    // ── Story 60.2: Pre-flight Trigger Check ────────────────────────────
-    /**
-     * Check if a trigger is allowed for the current tier WITHOUT calling the server.
-     * Returns immediately (in-memory lookup).
-     * NEVER throws - returns { allowed: true } on failure (fail-open).
-     */
-    async preFlightCheck(trigger, tier) {
-        try {
-            const userTier = tier ?? await this.getCachedTier();
-            const requiredTier = TRIGGER_GATES[trigger] ?? 'free';
-            if (TIER_HIERARCHY[userTier] >= TIER_HIERARCHY[requiredTier]) {
-                return { allowed: true };
-            }
-            const message = this.buildUpgradeMessage(trigger, userTier, requiredTier);
-            return { allowed: false, message };
-        }
-        catch {
-            // Fail-open: allow on error
-            return { allowed: true };
-        }
-    }
-    // ── Story 60.3: Quota Cache from Response ───────────────────────────
-    /**
-     * Update cached quota from server response metadata.
-     * Called after each successful invoke.
-     */
-    async updateQuotaFromResponse(metadata) {
-        try {
-            const quotaRemaining = metadata.quotaRemaining;
-            if (!quotaRemaining)
-                return;
-            const snapshot = {
-                stepsRemaining: quotaRemaining.stepsRemaining ?? 0,
-                invocationsRemaining: quotaRemaining.invocationsRemaining ?? 0,
-                stepsLimit: quotaRemaining.stepsLimit ?? 0,
-                invocationsLimit: quotaRemaining.invocationsLimit ?? 0,
-                cachedAt: Date.now(),
-            };
-            const dateKey = this.getQuotaCacheKey();
-            await this.cache.set(dateKey, JSON.stringify(snapshot), QUOTA_TTL_MS).catch(() => { });
-        }
-        catch {
-            // Non-critical
-        }
-    }
-    /**
-     * Get cached quota for today.
-     * NEVER throws - returns null if cache empty or expired.
-     */
-    async getCachedQuota() {
-        try {
-            const dateKey = this.getQuotaCacheKey();
-            const raw = await this.cache.get(dateKey);
-            if (!raw)
-                return null;
-            const snapshot = JSON.parse(raw);
-            // Validate TTL (EncryptedCache already handles this, but double-check)
-            if (Date.now() - snapshot.cachedAt > QUOTA_TTL_MS)
-                return null;
-            return snapshot;
-        }
-        catch {
-            return null;
-        }
-    }
-    // ── Story 60.4: Offline Enforcement ─────────────────────────────────
-    /**
-     * Check quota in offline mode using cached data.
-     * NEVER throws - returns { allowed: true } on failure (fail-open).
-     *
-     * @param isOffline - Whether the circuit breaker is in L2+ degradation
-     */
-    async offlineQuotaCheck(isOffline = false) {
-        try {
-            if (!isOffline)
-                return { allowed: true };
-            const quota = await this.getCachedQuota();
-            // Fail-open: if no cached quota, allow
-            if (!quota)
-                return { allowed: true };
-            // Check steps
-            if (quota.stepsRemaining <= 0 && quota.stepsLimit > 0) {
-                return {
-                    allowed: false,
-                    message: `Daily step limit reached (${quota.stepsLimit}/${quota.stepsLimit}). Resets at 00:00 UTC.`,
-                };
-            }
-            // Check invocations
-            if (quota.invocationsRemaining <= 0 && quota.invocationsLimit > 0) {
-                return {
-                    allowed: false,
-                    message: `Daily invocation limit reached (${quota.invocationsLimit}/${quota.invocationsLimit}). Resets at 00:00 UTC.`,
-                };
-            }
-            return { allowed: true };
-        }
-        catch {
-            // Fail-open
-            return { allowed: true };
-        }
-    }
-    // ── Private Helpers ─────────────────────────────────────────────────
-    /**
-     * Extract tier from JWT payload via base64url decode.
-     * No cryptographic verification - client-side is UX only.
-     */
-    extractTierFromJwt(token) {
-        try {
-            const parts = token.split('.');
-            if (parts.length !== 3)
-                return DEFAULT_TIER;
-            // Decode base64url payload
-            const payload = parts[1];
-            const decoded = Buffer.from(payload, 'base64url').toString('utf8');
-            const claims = JSON.parse(decoded);
-            const tier = claims.tier;
-            if (tier && VALID_TIERS.has(tier)) {
-                return tier;
-            }
-            return DEFAULT_TIER;
-        }
-        catch {
-            return DEFAULT_TIER;
-        }
-    }
-    buildUpgradeMessage(trigger, currentTier, requiredTier) {
-        return `The *${trigger} command requires ${requiredTier.toUpperCase()} plan. Your current plan: ${currentTier.toUpperCase()}. Upgrade: neocortex.dev/pricing`;
-    }
-    getQuotaCacheKey() {
-        const now = new Date();
-        const dateStr = now.toISOString().slice(0, 10); // YYYY-MM-DD UTC
-        return `${QUOTA_CACHE_KEY_PREFIX}${dateStr}`;
-    }
-}
+const s="neocortex:tier",l="neocortex:quota:",d=3e5,p=36e5,n=new Set(["free","pro","enterprise"]),a="free",u={status:"free",init:"free","create-epic":"free","idea-diagnose":"free","idea-research":"free","generate-epic":"free",exec:"pro",yolo:"pro",epic:"pro","setup-branch":"free",diagnose:"free",research:"free","write-spec":"free","create-tasks":"free",implement:"free","update-memory":"free",commit:"free",sync:"free","create-pr":"free",review:"pro",merge:"free","fix-blocked":"free","finalize-epic":"free",cleanup:"free","resolve-conflicts":"free",audit:"free",menu:"free",plans:"free",billing:"free",subscribe:"free"},o={free:0,pro:1,enterprise:2};class T{cache;licenseClient;cachedTier=null;constructor(t){this.cache=t.cacheProvider,this.licenseClient=t.licenseClient}async getCachedTier(){try{if(this.cachedTier)return this.cachedTier;const t=await this.cache.get(s);if(t&&n.has(t))return this.cachedTier=t,this.cachedTier;const e=await this.licenseClient.getToken();if(e){const r=this.extractTierFromJwt(e);return this.cachedTier=r,this.cache.set(s,r,36e5).catch(()=>{}),r}return a}catch{return a}}async updateTier(t){try{if(!n.has(t))return;this.cachedTier=t,await this.cache.set(s,t,36e5).catch(()=>{})}catch{}}async invalidateTierCache(){try{this.cachedTier=null,await this.cache.clear().catch(()=>{})}catch{}}async preFlightCheck(t,e){try{const r=e??await this.getCachedTier(),i=u[t]??"free";return o[r]>=o[i]?{allowed:!0}:{allowed:!1,message:this.buildUpgradeMessage(t,r,i)}}catch{return{allowed:!0}}}async updateQuotaFromResponse(t){try{const e=t.quotaRemaining;if(!e)return;const r={stepsRemaining:e.stepsRemaining??0,invocationsRemaining:e.invocationsRemaining??0,stepsLimit:e.stepsLimit??0,invocationsLimit:e.invocationsLimit??0,cachedAt:Date.now()},i=this.getQuotaCacheKey();await this.cache.set(i,JSON.stringify(r),3e5).catch(()=>{})}catch{}}async getCachedQuota(){try{const t=this.getQuotaCacheKey(),e=await this.cache.get(t);if(!e)return null;const r=JSON.parse(e);return Date.now()-r.cachedAt>3e5?null:r}catch{return null}}async offlineQuotaCheck(t=!1){try{if(!t)return{allowed:!0};const e=await this.getCachedQuota();return e?e.stepsRemaining<=0&&e.stepsLimit>0?{allowed:!1,message:`Daily step limit reached (${e.stepsLimit}/${e.stepsLimit}). Resets at 00:00 UTC.`}:e.invocationsRemaining<=0&&e.invocationsLimit>0?{allowed:!1,message:`Daily invocation limit reached (${e.invocationsLimit}/${e.invocationsLimit}). Resets at 00:00 UTC.`}:{allowed:!0}:{allowed:!0}}catch{return{allowed:!0}}}extractTierFromJwt(t){try{const e=t.split(".");if(e.length!==3)return a;const r=e[1],i=Buffer.from(r,"base64url").toString("utf8"),c=JSON.parse(i).tier;return c&&n.has(c)?c:a}catch{return a}}buildUpgradeMessage(t,e,r){return`The *${t} command requires ${r.toUpperCase()} plan. Your current plan: ${e.toUpperCase()}. Upgrade: neocortex.dev/pricing`}getQuotaCacheKey(){const e=new Date().toISOString().slice(0,10);return`${l}${e}`}}export{T as TierAwareClient};

package/packages/client/dist/types/index.js

@@ -1,38 +1 @@
-/**
- * @license FSL-1.1
- * Copyright (c) 2026 OrNexus AI
- *
- * This file is part of Neocortex CLI, licensed under the
- * Functional Source License, Version 1.1 (FSL-1.1).
- *
- * Change Date: February 20, 2029
- * Change License: MIT
- *
- * See the LICENSE file in the project root for full license text.
- */
-/**
- * @neocortex/client - Type Definitions
- *
- * All types for the asset resolution abstraction layer.
- */
-// ── Resolver Mode ────────────────────────────────────────────────────────
-/** Mode of asset resolution */
-export var ResolverMode;
-(function (ResolverMode) {
-    /** Read assets from local filesystem (development) */
-    ResolverMode["LOCAL"] = "local";
-    /** Fetch assets from remote IP Protection Server (production) */
-    ResolverMode["REMOTE"] = "remote";
-})(ResolverMode || (ResolverMode = {}));
-/** No-op cache implementation for development/fallback */
-export class NoOpCache {
-    async get() {
-        return null;
-    }
-    async set() {
-        // No-op: cache disabled
-    }
-    async clear() {
-        // No-op: nothing to clear
-    }
-}
+var a;(function(e){e.LOCAL="local",e.REMOTE="remote"})(a||(a={}));class c{async get(){return null}async set(){}async clear(){}}export{c as NoOpCache,a as ResolverMode};

package/targets-stubs/antigravity/gemini.md

@@ -1,4 +1,4 @@
-# 🧠 Neocortex v4.0.1 | OrNexus Team
+# 🧠 Neocortex v4.0.2 | OrNexus Team
 
 This project uses Neocortex, a Development Orchestrator.
 

package/targets-stubs/antigravity/install-antigravity.sh

@@ -2,6 +2,53 @@
 # Neocortex - Google Antigravity Install Adapter (Thin Client)
 # Simplified installer for npm tarball mode (targets-stubs only)
 
+# Additive JSON merge for Antigravity MCP config (flat JSON, keys are server names).
+# Preserves user-defined servers. Never overwrites silently.
+_merge_antigravity_mcp() {
+    local stub_file="$1"
+    local dest_file="$2"
+
+    if [ ! -f "$dest_file" ]; then
+        cp "$stub_file" "$dest_file"
+        echo "[ANTIGRAVITY] Created MCP config: $dest_file"
+        return 0
+    fi
+
+    if command -v jq >/dev/null 2>&1; then
+        local tmp="${dest_file}.neocortex.tmp"
+        if jq -s '.[0] * .[1]' "$dest_file" "$stub_file" > "$tmp" 2>/dev/null; then
+            mv "$tmp" "$dest_file"
+            echo "[ANTIGRAVITY] Merged MCP config into: $dest_file (via jq)"
+            return 0
+        fi
+        rm -f "$tmp"
+    fi
+
+    if command -v python3 >/dev/null 2>&1; then
+        if python3 - "$dest_file" "$stub_file" <<'PYEOF' 2>/dev/null
+import json, sys
+dest_path, stub_path = sys.argv[1], sys.argv[2]
+with open(dest_path) as f:
+    dest = json.load(f)
+with open(stub_path) as f:
+    stub = json.load(f)
+for k, v in stub.items():
+    dest[k] = v
+with open(dest_path, 'w') as f:
+    json.dump(dest, f, indent=2)
+    f.write('\n')
+PYEOF
+        then
+            echo "[ANTIGRAVITY] Merged MCP config into: $dest_file (via python3)"
+            return 0
+        fi
+    fi
+
+    echo "[ANTIGRAVITY] WARN: jq and python3 not found; leaving existing $dest_file untouched"
+    echo "[ANTIGRAVITY] WARN: Stub available at: $stub_file"
+    return 0
+}
+
 install_antigravity() {
     local source_dir="${1:?SOURCE_DIR required}"
     local dest_dir="${2:?DEST_DIR required}"
@@ -26,10 +73,9 @@ install_antigravity() {
         echo "[ANTIGRAVITY] Installed skill stub: .agent/skills/neocortex/SKILL.md"
     fi
 
-    # 2. Copy MCP config
+    # 2. Additive merge MCP config (preserves user-configured servers)
     if [ -f "$ag_target/mcp-config.json" ]; then
-        cp "$ag_target/mcp-config.json" "$gemini_home/antigravity/mcp_config.json"
-        echo "[ANTIGRAVITY] Installed MCP config: ~/.gemini/antigravity/mcp_config.json"
+        _merge_antigravity_mcp "$ag_target/mcp-config.json" "$gemini_home/antigravity/mcp_config.json" || true
     fi
 
     # 3. Copy GEMINI.md stub to project root

package/targets-stubs/antigravity/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: neocortex
-description: "🧠 Neocortex v4.0.1 | OrNexus Team"
+description: "🧠 Neocortex v4.0.2 | OrNexus Team"
 ---
 
 <!-- CRITICAL: Plugin Conflict Prevention -->
@@ -61,7 +61,26 @@ neocortex-client invoke \
 
 ## Regras
 
-- NUNCA invente logica de orquestracao - toda logica vem do server
-- NUNCA pule o thin client - sempre execute o invoke
-- SEMPRE siga as instrucoes retornadas literalmente
+### Orquestracao (triggers `*xxx`)
+- NUNCA invente logica de orquestracao - toda logica de pipeline/step/workflow vem do server
+- NUNCA pule o thin client para argumentos prefixados com `*` - sempre execute `neocortex-client invoke`
+- SEMPRE siga as instrucoes retornadas pelo server literalmente
 - Se o thin client falhar, mostre o erro e aguarde input do usuario
+
+### Pesquisa livre / analise (sem prefixo `*`)
+Quando o usuario pedir pesquisa, analise, brainstorm, validacao de hipotese, ou qualquer
+tarefa free-form que NAO seja um trigger de orquestracao, voce TEM permissao para usar
+diretamente as tools do Antigravity:
+
+- **File operations** (read / write / edit / glob / grep) - exploracao e manipulacao do projeto local
+- **Shell / terminal** - qualquer ferramenta CLI (jq, curl, psql, docker, fly, gh, etc.)
+- **Browser automation** (built-in via Antigravity's browser tools) - screenshots,
+  visual research, scraping
+- **Web search / fetch** - pesquisa de mercado, validacao de hipoteses, references reais
+- **MCP servers configurados** (context7, playwright) - documentacao atualizada de
+  libs/frameworks, automacao de navegador adicional. Ver `~/.gemini/antigravity/mcp_config.json`.
+
+NUNCA recuse uma pesquisa por falta de tools. NUNCA fabrique fontes - se nao encontrar
+dados reais, diga isso explicitamente. Quando a pesquisa resultar em decisoes que
+precisem virar epic/stories, ai sim invoque `neocortex-client invoke --args "*create-epic ..."`
+para entrar no fluxo de orquestracao.

package/targets-stubs/claude-code/neocortex.agent.yaml

@@ -4,7 +4,7 @@ agent:
     name: 'Neocortex'
     title: 'Development Orchestrator'
     icon: '>'
-    version: '4.0.1'
+    version: '4.0.2'
     architecture: 'thin-client'
     module: stand-alone
     hasSidecar: false
@@ -18,7 +18,25 @@ agent:
     - Read
     - Write
     - Edit
+    - NotebookEdit
     - Glob
     - Grep
+    - Task
+    - TaskCreate
+    - Skill
+    - WebSearch
+    - WebFetch
+    - mcp__context7__resolve-library-id
+    - mcp__context7__query-docs
+    - mcp__playwright__browser_navigate
+    - mcp__playwright__browser_snapshot
+    - mcp__playwright__browser_take_screenshot
+    - mcp__playwright__browser_click
+    - mcp__playwright__browser_type
+    - mcp__playwright__browser_evaluate
+    - mcp__playwright__browser_console_messages
+    - mcp__playwright__browser_network_requests
+    - mcp__playwright__browser_wait_for
+    - mcp__playwright__browser_close
 
   instructions: neocortex.md

package/targets-stubs/claude-code/neocortex.md

@@ -1,39 +1,55 @@
 ---
 name: neocortex
-description: "🧠 Neocortex v4.0.1 | OrNexus Team"
+description: "🧠 Neocortex v4.0.2 | OrNexus Team"
 model: opus
 color: blue
 tools:
+  # File operations
   - Read
   - Write
   - Edit
+  - NotebookEdit
   - Glob
   - Grep
+
+  # Subagent delegation + planning + skills
   - Task
-  - "Bash(neocortex-client:*)"
-  - "Bash(neocortex:*)"
-  - "Bash(git:*)"
-  - "Bash(gh:*)"
-  - "Bash(npm:*)"
-  - "Bash(npx:*)"
-  - "Bash(node:*)"
-  - "Bash(tsx:*)"
-  - "Bash(curl:*)"
-  - "Bash(docker:*)"
-  - "Bash(fly:*)"
-  - "Bash(flyctl:*)"
-  - "Bash(jq:*)"
-  - "Bash(mkdir:*)"
-  - "Bash(rm:*)"
-  - "Bash(mv:*)"
-  - "Bash(cp:*)"
-  - "Bash(ls:*)"
-  - "Bash(cat:*)"
-  - "Bash(date:*)"
-  - "Bash(stat:*)"
-  - "Bash(hostname:*)"
-  - "Bash(mktemp:*)"
-  - "Bash(ps:*)"
+  - TaskCreate
+  - Skill
+
+  # Web research (essential for product/market/UX research that the server cannot resolve)
+  - WebSearch
+  - WebFetch
+
+  # Bash - full access (no allowlist) for maximum tool reach
+  - Bash
+
+  # MCP: context7 (current library/framework documentation)
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+
+  # MCP: playwright (browser automation for visual research, screenshots, scraping)
+  - mcp__playwright__browser_navigate
+  - mcp__playwright__browser_navigate_back
+  - mcp__playwright__browser_snapshot
+  - mcp__playwright__browser_take_screenshot
+  - mcp__playwright__browser_click
+  - mcp__playwright__browser_type
+  - mcp__playwright__browser_fill_form
+  - mcp__playwright__browser_select_option
+  - mcp__playwright__browser_hover
+  - mcp__playwright__browser_drag
+  - mcp__playwright__browser_press_key
+  - mcp__playwright__browser_evaluate
+  - mcp__playwright__browser_console_messages
+  - mcp__playwright__browser_network_requests
+  - mcp__playwright__browser_wait_for
+  - mcp__playwright__browser_resize
+  - mcp__playwright__browser_handle_dialog
+  - mcp__playwright__browser_file_upload
+  - mcp__playwright__browser_run_code
+  - mcp__playwright__browser_tabs
+  - mcp__playwright__browser_close
 ---
 
 <!-- CRITICAL: Plugin Conflict Prevention -->
@@ -66,7 +82,7 @@ SEMPRE que este agente for invocado, imprima o banner abaixo como PRIMEIRO outpu
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.0.1                             │
+│      ###  ########      v4.0.2                             │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │
@@ -119,7 +135,26 @@ neocortex-client invoke \
 
 ## Regras
 
-- NUNCA invente logica de orquestracao - toda logica vem do server
-- NUNCA pule o thin client - sempre execute o invoke
-- SEMPRE siga as instrucoes retornadas literalmente
+### Orquestracao (triggers `*xxx`)
+- NUNCA invente logica de orquestracao - toda logica de pipeline/step/workflow vem do server
+- NUNCA pule o thin client para argumentos prefixados com `*` - sempre execute `neocortex-client invoke`
+- SEMPRE siga as instrucoes retornadas pelo server literalmente
 - Se o thin client falhar, mostre o erro e aguarde input do usuario
+
+### Pesquisa livre / analise (sem prefixo `*`)
+Quando o usuario pedir pesquisa, analise, brainstorm, validacao de hipotese, ou qualquer
+tarefa free-form que NAO seja um trigger de orquestracao, voce TEM permissao para usar
+diretamente as tools disponiveis:
+
+- **WebSearch / WebFetch** - pesquisa de mercado, validacao de hipoteses, references reais
+- **Context7 MCP** (`mcp__context7__*`) - documentacao atualizada de libs/frameworks
+- **Playwright MCP** (`mcp__playwright__*`) - screenshots, visual research, scraping
+- **Bash** - qualquer ferramenta CLI (jq, curl, psql, kubectl, docker, fly, gh, etc.)
+- **Read / Write / Edit / Glob / Grep / NotebookEdit** - manipulacao do projeto local
+- **Task** - delegar para subagentes especializados quando util
+- **Skill** - invocar skills do harness quando aplicavel
+
+NUNCA recuse uma pesquisa por falta de tools. NUNCA fabrique fontes - se nao encontrar
+dados reais, diga isso explicitamente. Quando a pesquisa resultar em decisoes que
+precisem virar epic/stories, ai sim invoque `neocortex-client invoke --args "*create-epic ..."`
+para entrar no fluxo de orquestracao.

package/targets-stubs/codex/agents.md

@@ -16,7 +16,7 @@ Codex built-in commands or actions.
 
 <!-- END: Plugin Conflict Prevention -->
 
-# Neocortex v4.0.1 | OrNexus Team
+# Neocortex v4.0.2 | OrNexus Team
 
 You are a Development Orchestrator. All orchestration logic is delivered by the remote Neocortex server.
 
@@ -55,7 +55,24 @@ neocortex-client invoke \
 
 ## Rules
 
-- NEVER invent orchestration logic - all logic comes from the server
-- NEVER skip the thin client - always execute invoke
+### Orchestration (triggers `*xxx`)
+- NEVER invent orchestration logic - all pipeline/step/workflow logic comes from the server
+- NEVER skip the thin client for `*`-prefixed arguments - always execute `neocortex-client invoke`
 - ALWAYS follow the returned instructions literally
 - If the thin client fails, show the error and wait for user input
+
+### Free research / analysis (no `*` prefix)
+When the user asks for research, analysis, brainstorming, hypothesis validation, or any
+free-form task that is NOT an orchestration trigger, you ARE allowed to use Codex CLI's
+built-in capabilities directly:
+
+- **File operations** (`apply_patch`, `shell` / file reads and edits) - local project exploration and edits
+- **Shell commands** (`shell` tool) - any CLI tool (curl, jq, psql, docker, fly, gh, grep, find, etc.)
+  to fetch docs, inspect systems, run tests, or gather evidence
+- **MCP servers configured** (context7, playwright, browser_use) - up-to-date library docs,
+  browser automation, visual research. See `~/.codex/config.toml` for MCP setup.
+
+NEVER refuse research for lack of tools. NEVER fabricate sources - if you cannot find
+real data, say so explicitly. When research leads to decisions that should become
+an epic/stories, invoke `neocortex-client invoke --args "*create-epic ..."` to enter
+the orchestration flow.

package/targets-stubs/codex/config-mcp.toml

@@ -4,3 +4,8 @@ args = ["-y", "@playwright/mcp@latest"]
 
 [mcp_servers.context7]
 url = "https://mcp.context7.com/mcp"
+
+[mcp_servers.browser_use]
+command = "npx"
+args = ["-y", "browser-use-mcp"]
+env = { BROWSER_USE_API_KEY = "${BROWSER_USE_API_KEY}" }

package/targets-stubs/cursor/agent.md

@@ -1,6 +1,6 @@
 ---
 name: neocortex
-description: "🧠 Neocortex v4.0.1 | OrNexus Team"
+description: "🧠 Neocortex v4.0.2 | OrNexus Team"
 model: fast
 readonly: false
 is_background: false
@@ -36,7 +36,7 @@ SEMPRE que este agente for invocado, imprima o banner abaixo como PRIMEIRO outpu
 ┌────────────────────────────────────────────────────────────┐
 │                                                            │
 │       #######           N E O C O R T E X                  │
-│      ###  ########      v4.0.1                             │
+│      ###  ########      v4.0.2                             │
 │ #########      #####                                       │
 │ ##    ##############    Development Orchestrator           │
 │ ##   ###  ######  ##    OrNexus Team                       │
@@ -88,7 +88,25 @@ neocortex-client invoke \
 
 ## Regras
 
-- NUNCA invente logica de orquestracao - toda logica vem do server
-- NUNCA pule o thin client - sempre execute o invoke
-- SEMPRE siga as instrucoes retornadas literalmente
+### Orquestracao (triggers `*xxx`)
+- NUNCA invente logica de orquestracao - toda logica de pipeline/step/workflow vem do server
+- NUNCA pule o thin client para argumentos prefixados com `*` - sempre execute `neocortex-client invoke`
+- SEMPRE siga as instrucoes retornadas pelo server literalmente
 - Se o thin client falhar, mostre o erro e aguarde input do usuario
+
+### Pesquisa livre / analise (sem prefixo `*`)
+Quando o usuario pedir pesquisa, analise, brainstorm, validacao de hipotese, ou qualquer
+tarefa free-form que NAO seja um trigger de orquestracao, voce TEM permissao para usar
+diretamente as tools do Cursor:
+
+- **Codebase search / grep / read file** - exploracao e analise do projeto local
+- **Web search / fetch** - pesquisa de mercado, validacao de hipoteses, references reais
+- **Terminal (`run_terminal`)** - qualquer ferramenta CLI (jq, curl, psql, docker, fly, gh, etc.)
+- **Edit file / apply patch** - manipulacao direta do projeto quando solicitado
+- **MCP servers configurados** (context7, playwright, browser_use) - documentacao atualizada,
+  browser automation, visual research
+
+NUNCA recuse uma pesquisa por falta de tools. NUNCA fabrique fontes - se nao encontrar
+dados reais, diga isso explicitamente. Quando a pesquisa resultar em decisoes que
+precisem virar epic/stories, ai sim invoque `neocortex-client invoke --args "*create-epic ..."`
+para entrar no fluxo de orquestracao.