screenhand 0.4.0 → 0.4.1

package/dist/mcp-desktop.js

@@ -5289,6 +5289,16 @@ function getJobRunner() {
             const client = await CDPClient({ port });
             return { Runtime: client.Runtime, Input: client.Input, close: () => client.close() };
         });
+        // Wire AppleScript runner into playbook engine for applescript steps
+        playbookEngine.setAppleScriptRunner(async (script) => {
+            if (process.platform === "win32")
+                throw new Error("AppleScript is not supported on Windows");
+            const { execSync } = await import("node:child_process");
+            return execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, {
+                encoding: "utf-8",
+                timeout: 15000,
+            }).trim();
+        });
         activeJobRunner = new JobRunner(bridge, jobManager, leaseManager, supervisor, (() => {
             const cfg = {
                 hasCDP: cdpPort !== null,

package/dist/src/ingestion/coverage-auditor.js

@@ -39,7 +39,7 @@ export class CoverageAuditor {
      */
     audit(bundleId, appName, menuScan) {
         const refs = this.loadReferences(bundleId);
-        const playbooks = this.loadPlaybooks(bundleId);
+        const playbooks = this.loadPlaybooks(bundleId, appName);
         // Count what we know
         let shortcutsKnown = 0;
         let selectorsKnown = 0;
@@ -208,8 +208,12 @@ export class CoverageAuditor {
         catch { /* dir not found */ }
         return refs;
     }
-    loadPlaybooks(bundleId) {
+    loadPlaybooks(bundleId, appName) {
         const playbooks = [];
+        // Derive short platform name from bundleId: "com.apple.Notes" → "notes"
+        const bundleParts = bundleId.split(".");
+        const shortName = (bundleParts[bundleParts.length - 1] ?? "").toLowerCase();
+        const appNameLower = appName.toLowerCase();
         try {
             const files = fs.readdirSync(this.playbooksDir);
             for (const file of files) {
@@ -218,7 +222,12 @@ export class CoverageAuditor {
                 try {
                     const raw = fs.readFileSync(path.join(this.playbooksDir, file), "utf-8");
                     const pb = JSON.parse(raw);
-                    if (pb.bundleId === bundleId || pb.platform === bundleId) {
+                    // Match by bundleId (exact), platform name (case-insensitive), or app name
+                    const platformLower = (pb.platform ?? "").toLowerCase();
+                    if (pb.bundleId === bundleId ||
+                        platformLower === bundleId ||
+                        platformLower === shortName ||
+                        platformLower === appNameLower) {
                         playbooks.push(pb);
                     }
                 }

package/dist/src/ingestion/feature-extractor.js

@@ -1,27 +1,27 @@
 // Copyright (C) 2025 Clazro Technology Private Limited
 // SPDX-License-Identifier: AGPL-3.0-only
-// ── Level assignment keywords ─────────────────────────────────────
+// ── Tier assignment keywords (F=entry, B=proficient, S=expert, SSS=grandmaster) ─
 /** Single-word keywords checked individually */
-const BEGINNER_WORDS = new Set([
+const F_WORDS = new Set([
     "basic", "create", "view", "share", "read",
     "browse", "search", "home", "start", "launch", "write",
 ]);
-const PRO_WORDS = new Set([
+const B_WORDS = new Set([
     "organize", "format", "customize", "template", "tag", "folder",
     "sort", "filter", "pin", "archive", "move", "rename", "duplicate",
     "favorites", "bookmark", "list", "table", "style", "font",
 ]);
-const EXPERT_WORDS = new Set([
+const S_WORDS = new Set([
     "automate", "shortcut", "export", "import", "collaborate", "sync",
     "scan", "link", "mention", "embed", "attachment", "password",
     "encrypt", "lock", "version", "history", "recover", "backup",
 ]);
-const GRANDMASTER_WORDS = new Set([
+const SSS_WORDS = new Set([
     "api", "integrate", "plugin", "advanced", "workflow", "script",
     "extension", "developer", "sdk", "automation", "pipeline", "webhook",
 ]);
 /** Multi-word phrases checked via substring match */
-const GRANDMASTER_PHRASES = [
+const SSS_PHRASES = [
     "custom action", "get started",
 ];
 // ── HTML entity decoding ──────────────────────────────────────────
@@ -97,32 +97,32 @@ function nameToId(name) {
 function assignLevel(name, description) {
     const text = `${name} ${description}`.toLowerCase();
     const words = text.split(/\s+/);
-    // Check multi-word grandmaster phrases first
-    for (const phrase of GRANDMASTER_PHRASES) {
+    // Check multi-word SSS phrases first
+    for (const phrase of SSS_PHRASES) {
         if (text.includes(phrase))
-            return "grandmaster";
+            return "SSS";
     }
     // Check single-word keywords
     for (const w of words) {
-        if (GRANDMASTER_WORDS.has(w))
-            return "grandmaster";
+        if (SSS_WORDS.has(w))
+            return "SSS";
     }
     for (const w of words) {
-        if (EXPERT_WORDS.has(w))
-            return "expert";
+        if (S_WORDS.has(w))
+            return "S";
     }
     for (const w of words) {
-        if (PRO_WORDS.has(w))
-            return "pro";
+        if (B_WORDS.has(w))
+            return "B";
     }
     for (const w of words) {
-        if (BEGINNER_WORDS.has(w))
-            return "beginner";
+        if (F_WORDS.has(w))
+            return "F";
     }
     // Fallback: longer descriptions suggest complexity
     if (description.length > 80)
-        return "pro";
-    return "beginner";
+        return "B";
+    return "F";
 }
 // ── Main: Extract features from HTML ──────────────────────────────
 export function extractFeaturesFromHTML(html, appName, url) {
@@ -252,7 +252,7 @@ const VALUE_ADD_RULES = [
             name: "Bulk Create",
             description: `Create multiple ${app} items from a list or template`,
             category: "bulk",
-            level: "pro",
+            level: "B",
         }),
     },
     {
@@ -263,7 +263,7 @@ const VALUE_ADD_RULES = [
             name: "Bulk Delete",
             description: `Delete multiple ${app} items matching criteria`,
             category: "bulk",
-            level: "pro",
+            level: "B",
         }),
     },
     {
@@ -274,7 +274,7 @@ const VALUE_ADD_RULES = [
             name: "Bulk Export",
             description: `Export all ${app} items at once`,
             category: "bulk",
-            level: "pro",
+            level: "B",
         }),
     },
     {
@@ -285,7 +285,7 @@ const VALUE_ADD_RULES = [
             name: "Auto-Organize",
             description: `Sort and organize ${app} items by content, date, or type`,
             category: "organization",
-            level: "expert",
+            level: "S",
         }),
     },
     {
@@ -296,7 +296,7 @@ const VALUE_ADD_RULES = [
             name: "Smart Search",
             description: `Search across all ${app} content with pattern matching`,
             category: "organization",
-            level: "pro",
+            level: "B",
         }),
     },
     {
@@ -307,7 +307,7 @@ const VALUE_ADD_RULES = [
             name: "Summarize",
             description: `Read and summarize all ${app} content`,
             category: "intelligence",
-            level: "expert",
+            level: "S",
         }),
     },
     {
@@ -318,7 +318,7 @@ const VALUE_ADD_RULES = [
             name: "Find Duplicates",
             description: `Identify duplicate or near-duplicate ${app} items`,
             category: "intelligence",
-            level: "expert",
+            level: "S",
         }),
     },
     {
@@ -329,7 +329,7 @@ const VALUE_ADD_RULES = [
             name: "Cross-App Export",
             description: `Export ${app} content to other apps automatically`,
             category: "cross_app",
-            level: "expert",
+            level: "S",
         }),
     },
     {
@@ -340,7 +340,7 @@ const VALUE_ADD_RULES = [
             name: "Cross-App Import",
             description: `Import content from other apps into ${app}`,
             category: "cross_app",
-            level: "expert",
+            level: "S",
         }),
     },
     {
@@ -351,7 +351,7 @@ const VALUE_ADD_RULES = [
             name: "Change Monitor",
             description: `Monitor ${app} for changes and notify`,
             category: "monitoring",
-            level: "grandmaster",
+            level: "SSS",
         }),
     },
 ];

package/dist/src/memory/playbook-seeds.js

@@ -50,7 +50,7 @@ export function seedErrorsFromPlaybooks(playbooksDir) {
     for (const pb of playbooks) {
         const platform = pb.platform ?? pb.id ?? "unknown";
         // Extract from errors[]
-        if (pb.errors) {
+        if (pb.errors && Array.isArray(pb.errors)) {
             for (const err of pb.errors) {
                 const key = `${platform}::${err.error}`;
                 if (seen.has(key))

package/dist/src/playbook/engine.js

@@ -20,6 +20,7 @@ const STEP_DELAY_MS = 300;
 export class PlaybookEngine {
     runtime;
     cdpConnect;
+    appleScriptRunner;
     /** Enable observer-based popup checks before each step */
     popupCheckEnabled = false;
     constructor(runtime) {
@@ -33,6 +34,10 @@ export class PlaybookEngine {
     setCDPConnect(factory) {
         this.cdpConnect = factory;
     }
+    /** Set AppleScript runner for applescript steps. Runner should execute the script and return stdout. */
+    setAppleScriptRunner(runner) {
+        this.appleScriptRunner = runner;
+    }
     /**
      * Execute a playbook against a live session.
      * Returns result with success/failure and which step broke.
@@ -284,6 +289,14 @@ export class PlaybookEngine {
                     await client.close();
                 }
             }
+            case "applescript": {
+                if (!step.script)
+                    throw new Error("applescript step missing script");
+                if (!this.appleScriptRunner)
+                    throw new Error("applescript requires runner — call setAppleScriptRunner() first");
+                const result = await this.appleScriptRunner(step.script);
+                return `applescript: ${result.substring(0, 200)}`;
+            }
             default:
                 throw new Error(`Unknown action: ${step.action}`);
         }
@@ -312,6 +325,8 @@ export class PlaybookEngine {
             result.verify = sub(result.verify);
         if (result.menuPath)
             result.menuPath = result.menuPath.map(sub);
+        if (result.script)
+            result.script = sub(result.script);
         return result;
     }
     /**

package/dist/src/playbook/mcp-recorder.js

@@ -28,18 +28,30 @@ const SKIP_TOOLS = new Set([
     "codex_monitor_start", "codex_monitor_status", "codex_monitor_add_task",
     "codex_monitor_tasks", "codex_monitor_assign_now", "codex_monitor_stop",
     "platform_learn", "platform_explore",
+    // Observation tools — not steps
+    "read_with_fallback", "locate_with_fallback", "execution_plan",
+    "browser_stealth",
+    // Observer/orchestrator lifecycle — not steps
+    "observer_start", "observer_stop", "observer_status", "observer_ocr_roi",
+    "orchestrator_start", "orchestrator_stop", "orchestrator_submit", "orchestrator_status",
+    // Ingestion/discovery — learning, not steps
+    "scan_menu_bar", "ingest_documentation", "ingest_tutorial",
+    "discover_features", "coverage_report",
 ]);
 /** Map MCP tool names to PlaybookStep actions */
 function mapToolToAction(toolName) {
     switch (toolName) {
-        case "browser_navigate": return "navigate";
+        case "browser_navigate":
+        case "browser_open": return "navigate";
         case "click":
         case "click_text":
         case "browser_click":
+        case "browser_human_click":
         case "click_with_fallback":
         case "ui_press": return "press";
         case "type_text":
         case "browser_type":
+        case "browser_fill_form":
         case "type_with_fallback": return "type_into";
         case "key": return "key";
         case "menu_click": return "menu_click";
@@ -50,6 +62,9 @@ function mapToolToAction(toolName) {
         case "screenshot_file": return "screenshot";
         case "browser_wait":
         case "wait_for_state": return "wait";
+        case "applescript": return "applescript";
+        case "ui_set_value": return "type_into";
+        case "select_with_fallback": return "press";
         case "focus":
         case "launch": return null; // useful context but not a step
         case "drag": return null; // drag is complex, skip for now
@@ -108,6 +123,10 @@ function buildStep(toolName, params, success) {
             step.ms = Number(params.timeout ?? params.ms ?? params.timeoutMs ?? 1000);
             step.description = `Wait ${step.ms}ms`;
             break;
+        case "applescript":
+            step.script = String(params.script ?? "");
+            step.description = `AppleScript: ${step.script.substring(0, 80)}${step.script.length > 80 ? "..." : ""}`;
+            break;
     }
     if (!success) {
         step.optional = true;
@@ -168,6 +187,7 @@ export class McpPlaybookRecorder {
             ...(typeof s.target === "string" ? { target: redactPII(s.target) } : {}),
             ...(s.url ? { url: redactPII(s.url) } : {}),
             ...(s.code ? { code: redactPII(s.code) } : {}),
+            ...(s.script ? { script: redactPII(s.script) } : {}),
             ...(s.description ? { description: redactPII(s.description) } : {}),
         }));
         const playbook = {

package/dist/src/state/app-map.js

@@ -11,59 +11,59 @@ import { generateLadderFromReference } from "./ladder-generator.js";
 // Define what real users do at each level. Used to measure honest mastery.
 const BUILTIN_LADDERS = {
     "com.hnc.Discord": [
-        // ── Beginner: basic consumer actions (weight 1) ──
-        { id: "browse_channels", description: "Join servers and browse channels", level: "beginner", weight: 1, critical: false },
-        { id: "send_message", description: "Send messages, replies, emojis, and reactions", level: "beginner", weight: 1, critical: false },
-        { id: "direct_messages", description: "Direct messages and group chats", level: "beginner", weight: 1, critical: false },
-        { id: "voice_video", description: "Voice channels, video calls, and screen share", level: "beginner", weight: 1, critical: false },
-        // ── Pro: operational features (weight 2) ──
-        { id: "threads_forums", description: "Create and manage threads and forum channels", level: "pro", weight: 2, critical: false },
-        { id: "roles_permissions", description: "Configure roles, overrides, inheritance, hidden channels", level: "pro", weight: 2, critical: true },
-        { id: "events_stage", description: "Schedule events, run Stage channels, manage speakers", level: "pro", weight: 2, critical: false },
-        { id: "onboarding_funnel", description: "Build join flows: rules screening, role assignment, starter channels", level: "pro", weight: 2, critical: true },
-        { id: "notification_control", description: "Channel overrides, mention control, suppression settings", level: "pro", weight: 1, critical: false },
-        // ── Expert: system-level features (weight 2-3) ──
-        { id: "moderation_system", description: "Configure AutoMod, mod bots, alert flows, ban appeals, raid defense", level: "expert", weight: 3, critical: true },
-        { id: "bot_ecosystem", description: "Combine bots, slash commands, webhooks into coherent server OS", level: "expert", weight: 3, critical: true },
-        { id: "server_architecture", description: "Design categories, channel taxonomy, permissions, escalation paths", level: "expert", weight: 3, critical: true },
-        { id: "community_growth", description: "Events, role rewards, content loops, announcements, retention mechanics", level: "expert", weight: 2, critical: false },
-        { id: "analytics_health", description: "Track activity patterns, onboarding drop-off, channel usage, retention", level: "expert", weight: 2, critical: true },
-        // ── Grandmaster: mastery-level operations (weight 3) ──
-        { id: "monetization_membership", description: "Premium roles, gated channels, supporter tiers, creator monetization", level: "grandmaster", weight: 2, critical: false },
-        { id: "crisis_handling", description: "Handle raids, harassment, spam, leaks, impersonation, conflicts", level: "grandmaster", weight: 3, critical: true },
-        { id: "cross_platform", description: "Connect Discord with GitHub, Notion, Twitch, Stripe, Zapier, tools", level: "grandmaster", weight: 2, critical: false },
-        { id: "staff_system", description: "Structure mod roles, escalation, internal channels, review processes", level: "grandmaster", weight: 3, critical: true },
-        { id: "brand_culture", description: "Shape tone, rituals, norms, recognition systems, community identity", level: "grandmaster", weight: 2, critical: false },
-        { id: "governance_policy", description: "Define rules, enforcement, appeals, social boundaries that hold up", level: "grandmaster", weight: 3, critical: true },
+        // ── F tier: basic consumer actions (weight 1) ──
+        { id: "browse_channels", description: "Join servers and browse channels", level: "F", weight: 1, critical: false },
+        { id: "send_message", description: "Send messages, replies, emojis, and reactions", level: "F", weight: 1, critical: false },
+        { id: "direct_messages", description: "Direct messages and group chats", level: "F", weight: 1, critical: false },
+        { id: "voice_video", description: "Voice channels, video calls, and screen share", level: "F", weight: 1, critical: false },
+        // ── B tier: operational features (weight 2) ──
+        { id: "threads_forums", description: "Create and manage threads and forum channels", level: "B", weight: 2, critical: false },
+        { id: "roles_permissions", description: "Configure roles, overrides, inheritance, hidden channels", level: "B", weight: 2, critical: true },
+        { id: "events_stage", description: "Schedule events, run Stage channels, manage speakers", level: "B", weight: 2, critical: false },
+        { id: "onboarding_funnel", description: "Build join flows: rules screening, role assignment, starter channels", level: "B", weight: 2, critical: true },
+        { id: "notification_control", description: "Channel overrides, mention control, suppression settings", level: "B", weight: 1, critical: false },
+        // ── S tier: system-level features (weight 2-3) ──
+        { id: "moderation_system", description: "Configure AutoMod, mod bots, alert flows, ban appeals, raid defense", level: "S", weight: 3, critical: true },
+        { id: "bot_ecosystem", description: "Combine bots, slash commands, webhooks into coherent server OS", level: "S", weight: 3, critical: true },
+        { id: "server_architecture", description: "Design categories, channel taxonomy, permissions, escalation paths", level: "S", weight: 3, critical: true },
+        { id: "community_growth", description: "Events, role rewards, content loops, announcements, retention mechanics", level: "S", weight: 2, critical: false },
+        { id: "analytics_health", description: "Track activity patterns, onboarding drop-off, channel usage, retention", level: "S", weight: 2, critical: true },
+        // ── SSS tier: grandmaster operations (weight 3) ──
+        { id: "monetization_membership", description: "Premium roles, gated channels, supporter tiers, creator monetization", level: "SSS", weight: 2, critical: false },
+        { id: "crisis_handling", description: "Handle raids, harassment, spam, leaks, impersonation, conflicts", level: "SSS", weight: 3, critical: true },
+        { id: "cross_platform", description: "Connect Discord with GitHub, Notion, Twitch, Stripe, Zapier, tools", level: "SSS", weight: 2, critical: false },
+        { id: "staff_system", description: "Structure mod roles, escalation, internal channels, review processes", level: "SSS", weight: 3, critical: true },
+        { id: "brand_culture", description: "Shape tone, rituals, norms, recognition systems, community identity", level: "SSS", weight: 2, critical: false },
+        { id: "governance_policy", description: "Define rules, enforcement, appeals, social boundaries that hold up", level: "SSS", weight: 3, critical: true },
     ],
     "com.apple.Safari": [
-        { id: "browse_navigate", description: "Open URLs and navigate pages", level: "beginner", weight: 1, critical: false },
-        { id: "tabs_windows", description: "Manage tabs and windows", level: "beginner", weight: 1, critical: false },
-        { id: "bookmarks", description: "Bookmarks and reading list", level: "beginner", weight: 1, critical: false },
-        { id: "history_search", description: "History and search", level: "beginner", weight: 1, critical: false },
-        { id: "tab_groups", description: "Tab groups and profiles", level: "pro", weight: 2, critical: false },
-        { id: "extensions", description: "Install and use extensions", level: "pro", weight: 2, critical: false },
-        { id: "dev_tools", description: "Web Inspector and developer tools", level: "expert", weight: 2, critical: true },
-        { id: "privacy_settings", description: "Privacy, cookies, and content blockers", level: "expert", weight: 2, critical: false },
-        { id: "web_apps", description: "Add to Dock, web apps, notifications", level: "grandmaster", weight: 2, critical: false },
+        { id: "browse_navigate", description: "Open URLs and navigate pages", level: "F", weight: 1, critical: false },
+        { id: "tabs_windows", description: "Manage tabs and windows", level: "F", weight: 1, critical: false },
+        { id: "bookmarks", description: "Bookmarks and reading list", level: "F", weight: 1, critical: false },
+        { id: "history_search", description: "History and search", level: "F", weight: 1, critical: false },
+        { id: "tab_groups", description: "Tab groups and profiles", level: "B", weight: 2, critical: false },
+        { id: "extensions", description: "Install and use extensions", level: "B", weight: 2, critical: false },
+        { id: "dev_tools", description: "Web Inspector and developer tools", level: "S", weight: 2, critical: true },
+        { id: "privacy_settings", description: "Privacy, cookies, and content blockers", level: "S", weight: 2, critical: false },
+        { id: "web_apps", description: "Add to Dock, web apps, notifications", level: "SSS", weight: 2, critical: false },
     ],
     "com.apple.finder": [
-        { id: "browse_files", description: "Browse and open files/folders", level: "beginner", weight: 1, critical: false },
-        { id: "copy_move", description: "Copy, move, rename, delete files", level: "beginner", weight: 1, critical: false },
-        { id: "search", description: "Spotlight and Finder search", level: "beginner", weight: 1, critical: false },
-        { id: "views_sort", description: "Change views, sort, and organize", level: "pro", weight: 2, critical: false },
-        { id: "tags_favorites", description: "Tags, favorites, and sidebar", level: "pro", weight: 2, critical: false },
-        { id: "quick_actions", description: "Quick Look, Quick Actions, and Services", level: "expert", weight: 2, critical: true },
-        { id: "automator_scripts", description: "Automator, terminal, and scripting", level: "grandmaster", weight: 2, critical: false },
+        { id: "browse_files", description: "Browse and open files/folders", level: "F", weight: 1, critical: false },
+        { id: "copy_move", description: "Copy, move, rename, delete files", level: "F", weight: 1, critical: false },
+        { id: "search", description: "Spotlight and Finder search", level: "F", weight: 1, critical: false },
+        { id: "views_sort", description: "Change views, sort, and organize", level: "B", weight: 2, critical: false },
+        { id: "tags_favorites", description: "Tags, favorites, and sidebar", level: "B", weight: 2, critical: false },
+        { id: "quick_actions", description: "Quick Look, Quick Actions, and Services", level: "S", weight: 2, critical: true },
+        { id: "automator_scripts", description: "Automator, terminal, and scripting", level: "SSS", weight: 2, critical: false },
     ],
 };
 /** Generic fallback ladder — used when no builtin AND no reference-generated ladder exists. */
 const GENERIC_LADDER = [
-    { id: "basic_navigation", description: "Open, navigate, and browse the app", level: "beginner", weight: 1, critical: false },
-    { id: "core_action", description: "Perform the app's primary action", level: "beginner", weight: 1, critical: false },
-    { id: "settings", description: "Configure settings and preferences", level: "pro", weight: 2, critical: false },
-    { id: "advanced_features", description: "Use advanced/power-user features", level: "expert", weight: 2, critical: true },
-    { id: "automation", description: "Automate or customize workflows", level: "grandmaster", weight: 3, critical: true },
+    { id: "basic_navigation", description: "Open, navigate, and browse the app", level: "F", weight: 1, critical: false },
+    { id: "core_action", description: "Perform the app's primary action", level: "F", weight: 1, critical: false },
+    { id: "settings", description: "Configure settings and preferences", level: "B", weight: 2, critical: false },
+    { id: "advanced_features", description: "Use advanced/power-user features", level: "S", weight: 2, critical: true },
+    { id: "automation", description: "Automate or customize workflows", level: "SSS", weight: 3, critical: true },
 ];
 /** Redact an array of user-facing strings in place, returning a new array. */
 function redactStrings(strings) {
@@ -289,11 +289,11 @@ export class AppMap {
         if (discoveredCount >= 30)
             return null;
         // Assign level based on tool complexity
-        let level = "beginner";
+        let level = "F";
         if (toolName === "menu_click" || toolName === "key")
-            level = "pro";
+            level = "B";
         if (toolName === "applescript" || toolName === "browser_js")
-            level = "expert";
+            level = "S";
         const feature = {
             id: featureId,
             description: `[auto] ${target}`,
@@ -1435,9 +1435,14 @@ export class AppMap {
         let totalFailures = 0;
         let weightedScore = 0;
         // Tier-scoped critical floor: only check critical features at or below the target tier
-        const tierOrder = ["beginner", "pro", "expert", "grandmaster"];
-        const scopeIdx = tierScope ? tierOrder.indexOf(tierScope) : 3; // default: all tiers
-        const scopedLevels = new Set(tierOrder.slice(0, scopeIdx + 1));
+        // MasteryLevel (deprecated) maps to FeatureTier: beginner→F, pro→B, expert→S, grandmaster→SSS
+        const masteryToFeatureTier = {
+            beginner: "F", pro: "B", expert: "S", grandmaster: "SSS",
+        };
+        const featureTierOrder = ["F", "B", "S", "SSS"];
+        const scopedFeatureTier = tierScope ? masteryToFeatureTier[tierScope] : "SSS";
+        const scopeIdx = featureTierOrder.indexOf(scopedFeatureTier);
+        const scopedLevels = new Set(featureTierOrder.slice(0, scopeIdx + 1));
         let criticalMinDepth = 999;
         let hasScopedCritical = false;
         for (const feature of ladder) {

package/dist/src/state/ladder-generator.js

@@ -1,19 +1,19 @@
 // Copyright (C) 2025 Clazro Technology Private Limited
 // SPDX-License-Identifier: AGPL-3.0-only
-// ── Keyword sets for level assignment ────────────────────────────
-const BEGINNER_KEYWORDS = new Set([
+// ── Keyword sets for tier assignment (F=entry, B=proficient, S=expert, SSS=grandmaster) ──
+const F_KEYWORDS = new Set([
     "navigation", "browse", "basic", "search", "header", "page", "nav", "home",
     "page_header", "quick_find",
 ]);
-const PRO_KEYWORDS = new Set([
+const B_KEYWORDS = new Set([
     "settings", "create", "views", "sort", "filter", "template", "new", "sidebar",
     "create_new", "slash_commands", "notification", "preferences",
 ]);
-const EXPERT_KEYWORDS = new Set([
+const S_KEYWORDS = new Set([
     "database", "admin", "moderation", "permissions", "automation", "advanced",
     "server", "import", "export", "workflow", "security", "form",
 ]);
-const GRANDMASTER_KEYWORDS = new Set([
+const SSS_KEYWORDS = new Set([
     "ai", "api", "integration", "custom", "governance", "crisis", "identity",
     "billing", "orchestrat", "pipeline",
 ]);
@@ -89,9 +89,9 @@ export function generateLadderFromReference(ref) {
             // where a short website feature id like "export" matches "export_pdf_flow")
             if (selectorGroups[wf.id] !== undefined || flows[wf.id] !== undefined)
                 continue;
-            const level = (["beginner", "pro", "expert", "grandmaster"].includes(wf.level)
+            const level = (["F", "B", "S", "SSS"].includes(wf.level)
                 ? wf.level
-                : "beginner");
+                : "F");
             const weight = assignWeight(wf.id, 0, level);
             features.push({
                 id: featureId,
@@ -109,9 +109,9 @@ export function generateLadderFromReference(ref) {
             const featureId = `va_${va.id}`;
             if (features.some((f) => f.id === featureId))
                 continue;
-            const level = (["pro", "expert", "grandmaster"].includes(va.level)
+            const level = (["B", "S", "SSS"].includes(va.level)
                 ? va.level
-                : "expert");
+                : "S");
             features.push({
                 id: featureId,
                 description: va.description,
@@ -124,7 +124,7 @@ export function generateLadderFromReference(ref) {
     }
     // ── Step 3: Sort by level progression ──────────────────────────
     const levelOrder = {
-        beginner: 0, pro: 1, expert: 2, grandmaster: 3,
+        F: 0, B: 1, S: 2, SSS: 3,
     };
     features.sort((a, b) => levelOrder[a.level] - levelOrder[b.level]);
     return { ladder: features, signals, hash: computeHash(ref) };
@@ -133,37 +133,37 @@ export function generateLadderFromReference(ref) {
 function assignLevel(name, selectorCount, isFlow, complexity) {
     const nameLower = name.toLowerCase();
     const parts = nameLower.split(/[_\s-]+/);
-    // Check grandmaster first (most specific)
-    if (parts.some(p => GRANDMASTER_KEYWORDS.has(p)))
-        return "grandmaster";
-    if (parts.some(p => EXPERT_KEYWORDS.has(p)))
-        return "expert";
-    if (parts.some(p => PRO_KEYWORDS.has(p)))
-        return "pro";
-    if (parts.some(p => BEGINNER_KEYWORDS.has(p)))
-        return "beginner";
+    // Check SSS first (most specific)
+    if (parts.some(p => SSS_KEYWORDS.has(p)))
+        return "SSS";
+    if (parts.some(p => S_KEYWORDS.has(p)))
+        return "S";
+    if (parts.some(p => B_KEYWORDS.has(p)))
+        return "B";
+    if (parts.some(p => F_KEYWORDS.has(p)))
+        return "F";
     // Fallback based on complexity
     if (isFlow) {
         if (complexity >= 8)
-            return "expert";
+            return "S";
         if (complexity >= 5)
-            return "pro";
-        return "beginner";
+            return "B";
+        return "F";
     }
     // Selector group: more selectors = more complex
     if (selectorCount >= 8)
-        return "expert";
+        return "S";
     if (selectorCount >= 4)
-        return "pro";
-    return "beginner";
+        return "B";
+    return "F";
 }
 // ── Weight assignment ────────────────────────────────────────────
 function assignWeight(name, complexity, level) {
-    if (level === "grandmaster")
+    if (level === "SSS")
         return 3;
-    if (level === "expert" && complexity >= 6)
+    if (level === "S" && complexity >= 6)
         return 3;
-    if (level === "expert" || level === "pro")
+    if (level === "S" || level === "B")
         return 2;
     return 1;
 }