jsgui3-server 0.0.152 → 0.0.155

package/docs/agi/skills/README.md

@@ -0,0 +1,23 @@
+# Skills (Capability Packs)
+
+This folder contains repo-native "Skill packs": discoverable, reusable capabilities inspired by Claude Code Agent Skills.
+
+A Skill is:
+- a `SKILL.md` with clear triggers + SOP
+- links to existing scripts/checks/tests (so validation is fast)
+- minimal content by default (expand only when needed)
+
+## Conventions
+
+- Folder name matches the skill name (lowercase, hyphenated)
+- `SKILL.md` frontmatter must include:
+  - `name`
+  - `description` (include trigger phrases and "Use when …")
+
+## How to expand a Skill
+
+If a Skill is missing critical steps or references:
+
+1. Add the missing pointers (docs/scripts/tests) first.
+2. Only then add new "how-to" prose.
+3. If new research is required, create a follow-up requesting research.

package/docs/agi/skills/agent-output-control/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: agent-output-control
+description: Standard Operating Procedure for varying agent output styles, controlling verbosity, and using information-dense emoji structures. Use this skill when asked to change your communication tone, increase conciseness, or design highly expressive console logging systems.
+---
+
+# Agent Output Control
+
+## Scope
+
+This Skill defines how agents should modulate their own communication streams (both to the user and within externalized code/logs). It covers variable verbosity, distinctive stylistic phrasing, and the experimental use of high-density emojis to convey complex state information instantly.
+
+## Triggers
+
+- "Change your output style"
+- "Be more concise", "Be more verbose"
+- "Use heavy emojis for logging", "Design expressive console logs"
+- "Write in a distinctive, information-dense style"
+
+## Methodology
+
+### 1. Modulating Verbosity and Phrasing
+Agents must be able to fluidly shift between communication modes based on user preference or task context:
+- **Maximum Conciseness (Terminal Mode):** Strip all conversational filler ("I will now...", "Here is the..."). Output strictly the required data, diffs, or Boolean confirmations. 
+- **High Verbosity (Didactic Mode):** Explain the *why* behind every action. Break down complex logic step-by-step, suitable for a tutorial or an architectural design doc.
+- **Distinctive Persona:** If requested to adopt a specific stylistic persona (e.g., highly formal, ultra-terse, or uniquely formatted), maintain that constraint strictly across all tool calls and user notifications.
+
+### 2. Experimental High-Density Emoji Usage
+Emojis are not just decorative; they are ultra-compact tokens that can convey state, direction, and domain instantly.
+- **State Indicators:** `🟢` (Healthy/Go), `🟡` (Yield/Warn), `🔴` (Halt/Error), `🔵` (Info/Cold), `🔥` (Hot/Intense).
+- **Domain Indicators:** `📦` (Database/Storage), `🌐` (Network/API), `🧠` (Agent/Logic), `🖥️` (UI/Frontend).
+- **Action Indicators:** `➡️` (Data Flow), `🔄` (Loop/Retry), `🛑` (Block), `✅` (Success), `❌` (Fail), `⏱️` (Timing/Latency).
+- **Density Protocol:** In "heavy emoji" mode, combine these tokens to create visual sentences. 
+  *Example:* Instead of typing "The HTTP server successfully started and is serving the page in 45ms", output: 
+  `[🌐 START ➡️ 🖥️ SERVE | ✅ 200 OK | ⏱️ 45ms]`
+
+### 3. Expressive Console Logging Design
+When writing or refactoring logger software (e.g., Node.js `console.log` wrappers), apply the exact same principles to the code:
+- **Visually Scannable:** Ensure logs begin with high-contrast emojis or color codes (via ANSI escape sequences) so developers can scan thousands of lines visually.
+- **Structured Density:** Design the ultimate log format to be both human-readable (via emojis/tags) and machine-parsable (e.g., appended JSON).
+- *Implementation Example in Code:*
+  ```javascript
+  const log_info = (msg, ms) => console.log(`🔵 [SYS] ➡️ ${msg} | ⏱️ ${ms}ms`);
+  const log_error = (api, err) => console.error(`🔴 [❌ FAIL: ${api}] 🔥 Err: ${err.message}`);
+  ```
+
+## Anti-Patterns to Avoid
+
+- **The Chatty Protocol**: Replying with 3 paragraphs of pleasantries when the user explicitly requested "Maximum Conciseness" or "Terminal Mode".
+- **Emoji Salad**: Using random or inconsistent emojis just to be colorful, which destroys their utility as scannable state indicators. Define a semantic mapping and stick to it.
+- **Monolithic Logs**: Writing console logs that are just giant blocks of monochrome text with no visual anchors or parseable structures.
+
+## Validation
+
+- Did you conform perfectly to the requested verbosity level (terse vs. verbose)?
+- If using high-density emojis, is there a clear, consistent semantic meaning to each glyph?
+- If generating logging code, does the code output visually scannable, information-dense strings?

package/docs/agi/skills/ai-deep-research/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ai-deep-research
+description: Conduct multi-step, iterative, and deep research on complex topics. Use when a query requires synthesizing information from multiple sources, understanding deep context, or when initial findings are insufficient.
+---
+
+# AI Deep Research
+
+## Scope
+
+This Skill provides a methodology for conducting deep, multi-step research. It is designed to move beyond simple queries and quick answers, enabling the agent to autonomously plan, execute, analyze, and synthesize complex information.
+
+## Triggers
+
+- "Deep research", "comprehensive analysis", "literature review"
+- Queries requiring data from multiple disparate sources
+- When initial searches yield superficial or insufficient results
+
+## Methodology & Procedure
+
+1. **Understand and Interactive Planning**: 
+   - Deconstruct complex queries into distinct sub-topics and required knowledge gaps.
+   - **Interactive Review:** Propose the research plan to the User for refinement. Do not execute a massive multi-hour research loop without verifying the direction.
+   - Consider multimodal contexts (images, audio, existing code) attached to the query.
+
+2. **Iterative Gathering & Tool Diversity**:
+   - Utilize diverse sources: public web (`search_web`), exact file reads (`read_url_content`), and private enterprise/contextual data via MCP servers.
+   - Use code interpreters or external tools to crunch numbers or validate math, rather than relying solely on LLM text generation.
+   - **Self-Correcting Loops:** If a search is too broad, pivot to semantic variations. If you hit a paywall, find alternative authoritative sources.
+
+3. **Deep Thinking & Parallel Synthesis**:
+   - **Source Validation & Bias Detection:** Actively cross-reference claims text. Discard low-credibility sources, identify biases, and verify facts before trusting them.
+   - **Parallel Thinking:** For highly complex or contradictory topics, simulate multiple hypotheses or "agents" evaluating the data simultaneously, then synthesize the most robust finding.
+   - **Deliberate Reasoning:** Dedicate extensive "thinking" effort to difficult logical problems. It is better to have a highly accurate, deeply reasoned insight than a verbose but shallow summary.
+
+4. **Generate Comprehensive Report**:
+   - Structure a highly organized report with logical sections (e.g., Executive Summary, Sub-topic Deep Dives, Synthesis/Conclusion).
+   - Ensure all claims are backed by exact verifiable citations and links.
+   - Summarize the confidence level of the findings and acknowledge the system's own limitations if data is missing.
+
+## Validation
+
+- Did you get User approval on the research plan before executing a massive loop?
+- Did you cross-reference facts across multiple, high-credibility sources?
+- Are contradictions between sources explicitly addressed ("Parallel Thinking")?
+- Does the final report directly answer the user's core, complex question with verifiable citations?
+
+## Anti-Patterns to Avoid
+
+- **Surface-Level Scraping**: Doing one search and just summarizing the first three hits.
+- **Echo Chambering**: Relying on a single biased source without cross-referencing.
+- **Task Fixation**: Sticking rigidly to the original search plan when initial searches prove fruitless or irrelevant.
+- **Citation Omission**: Presenting facts without noting explicitly where they came from.

package/docs/agi/skills/autonomous-ui-inspection/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: autonomous-ui-inspection
+description: Autonomous UI inspection using a dual channel — (1) visual screenshots via browser tools, (2) numeric layout metrics via Puppeteer scripts. Use when you need a reliable, agent-friendly view of what the UI renders.
+---
+
+# Autonomous UI Inspection
+
+## Scope
+
+Use this Skill when you need a **reliable, agent-friendly view of what the UI renders**:
+
+- **Visual**: screenshots + accessibility snapshots
+- **Numeric**: bounding boxes, computed styles, text overflow, and connection geometry (Puppeteer)
+
+This Skill is about **inspection and evidence collection**. It intentionally avoids styling tweaks unless the inspection workflow itself is broken.
+
+## Inputs
+
+- Which UI surface (server file + URL route)
+- Whether the UI is SSR-only or needs client activation
+- A stable selector that indicates "ready" (e.g. a control class or `data-role` attribute)
+- Desired viewport and whether you need a clipped screenshot
+
+## Procedure
+
+### A) Server start/stop
+
+1. Start the jsgui3-server instance being inspected:
+   ```bash
+   node examples/<example>/server.js
+   ```
+   Or for the main server:
+   ```bash
+   node server.js
+   ```
+
+2. Ensure the server is ready before inspection.
+
+### B) Visual inspection (Browser tools)
+
+Goal: get screenshots that an agent can "see", plus a structural snapshot.
+
+1. Start the UI server.
+2. Navigate to the URL using browser tools.
+3. Capture:
+   - Full-page screenshot (baseline)
+   - Optional clipped screenshot (if a stable container selector exists)
+   - Accessibility snapshot for structure + quick DOM sanity
+
+Notes:
+- Use consistent viewport dimensions (example: 1600x1200) to reduce diff noise.
+- If the UI is interactive, capture "before" and "after" screenshots for a single canonical interaction.
+
+### C) Numeric inspection (Puppeteer)
+
+Goal: compute layout facts agents can diff and enforce.
+
+Run a dedicated Puppeteer script that:
+
+- Starts the server on a random or fixed dev port
+- Waits for a deterministic "ready" selector
+- Extracts metrics:
+  - `getBoundingClientRect()` for key elements
+  - `scrollWidth/Height` vs `clientWidth/Height` for overflow
+  - computed styles for typography + spacing
+
+Typical invariants to enforce:
+- Text is not overflowing (`isOverflowing === false`)
+- Bounding boxes are within expected ranges
+- Key interactive elements are visible
+
+### D) WebSocket / live-update verification
+
+When a page uses WebSocket for real-time updates:
+
+1. Verify WebSocket connection:
+   ```javascript
+   // Puppeteer: check WebSocket is established
+   const ws_messages = [];
+   page.on('websocket', ws => {
+     ws.on('framereceived', frame => ws_messages.push(JSON.parse(frame.payload)));
+   });
+   await page.goto(url);
+   await page.waitForTimeout(2000);
+   console.log('WS messages received:', ws_messages.length);
+   ```
+
+2. Verify DOM updates happen without reload.
+3. Test reconnect behavior if applicable.
+
+## Validation / Evidence Checklist
+
+- Server starts and responds on the expected port
+- At least one screenshot captured
+- Numeric JSON output captured (stdout or written artifact)
+- A "ready selector" exists and is documented for the UI
+
+## References
+
+- Puppeteer efficient verification: `docs/agi/skills/puppeteer-efficient-ui-verification/SKILL.md`
+- jsgui3 understanding: `docs/agi/skills/understanding-jsgui3/SKILL.md`
+- Server documentation: `docs/comprehensive-documentation.md`

package/docs/agi/skills/deep-research/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: deep-research
+description: Conduct deep, multi-step research on a topic using iterative search-evaluate-refine loops with deep thinking reasoning. Use when you need comprehensive understanding of a topic, technology, or problem space — not just a quick answer.
+---
+
+# Skill: Deep Research (with Deep Thinking Reasoning)
+
+## Scope
+
+Use this Skill when you need to **deeply understand a topic** — not just find a quick answer, but build comprehensive, validated knowledge:
+
+- You need to research a technology, architecture, or design pattern in depth.
+- You need to compare approaches and make an evidence-based recommendation.
+- You need to produce a detailed report, book chapter, specification, or analysis.
+- You need to investigate a problem space where the first answer is probably incomplete.
+- You want to combine information from multiple sources into a coherent synthesis.
+
+This is the research equivalent of "think hard before answering." It is **not** for quick lookups — use normal web search for those.
+
+## Core Principles
+
+### 1. Think Before You Search
+
+Before any search, articulate:
+- **What do I already know** about this topic?
+- **What are my knowledge gaps?** (Be honest about uncertainty)
+- **What specific questions** would fill those gaps?
+- **What assumptions am I making?** (Write them down — see Key Assumptions Check below)
+
+### 2. Search Wide, Then Deep (Progressive Deepening)
+
+```
+Round 1: Broad landscape scan
+  → "What is X? How does X work? X overview"
+  → Goal: Identify the key concepts, players, and terminology
+
+Round 2: Targeted investigation
+  → "X vs Y comparison", "X architecture internals", "X best practices"
+  → Goal: Understand the mechanics, trade-offs, and expert opinions
+
+Round 3: Deep dives on specifics
+  → "X edge cases", "X implementation gotchas", "X academic paper"
+  → Goal: Fill remaining gaps, find contrarian views, verify claims
+
+Round 4 (if needed): Adversarial search
+  → "X criticisms", "X failures", "why X is bad", "X alternatives"
+  → Goal: Stress-test your conclusions with disconfirming evidence
+```
+
+### 3. Grade Your Evidence
+
+| Level | Label | Description | Examples |
+|-------|-------|-------------|----------|
+| **A** | **High** | Primary source, authoritative, current | Official docs, author's blog, peer-reviewed paper, source code |
+| **B** | **Moderate** | Credible secondary source, well-reasoned | Reputable tech blog, conference talk, well-cited Stack Overflow |
+| **C** | **Low** | Unverified or potentially outdated | Random blog post, forum comment, undated article |
+| **D** | **Very Low** | Anecdotal, potentially unreliable | Social media, AI-generated content, marketing material |
+
+### 4. Reason Deeply Between Searches (Deep Thinking)
+
+After each search round, **stop and think**:
+- What did I learn that I didn't know before?
+- What contradictions or surprises did I find?
+- What is still unclear or unconfirmed?
+- Have my initial assumptions changed?
+- What should I search for next?
+
+## Procedure
+
+### Phase 0 — Frame the Research
+1. **State the research objective** in one sentence.
+2. **List what you already know** (even if tentative).
+3. **List 3–5 specific questions** you need answered.
+4. **Perform a Key Assumptions Check** (KAC).
+5. **Define the output format**: report, comparison table, specification, etc.
+6. **Set a depth budget**: how many search rounds are appropriate? (Typically 3–5)
+
+### Phase 1 — Landscape Scan (Broad)
+1. Run 2–3 broad web searches with different phrasings.
+2. Read the top results. Skim for structure, not detail.
+3. **Pause and reason**.
+4. **Build an evidence map**.
+5. Update your question list.
+
+### Phase 2 — Targeted Investigation (Focused)
+1. Search for specific sub-topics identified in Phase 1.
+2. Read primary sources when possible.
+3. **Grade each source** using the evidence grading scale.
+4. **Pause and reason**.
+5. Start building your synthesis outline.
+
+### Phase 3 — Deep Dives (Specific)
+1. Search for specific unanswered questions from Phase 2.
+2. **Actively look for disconfirming evidence**.
+3. Check for recent developments.
+4. Read code, specifications, or academic sources if relevant.
+5. **Pause and reason**.
+
+### Phase 4 — Synthesis (Deep Thinking)
+1. **Organise your findings** into a coherent structure.
+2. **Cross-reference claims**.
+3. **Identify your own reasoning gaps**.
+4. **Apply reasoning techniques**: Chain of Thought, Tree of Thought, Analysis of Competing Hypotheses, Self-Reflection.
+5. **Perform a sensitivity analysis**.
+6. **Write the output** with proper sourcing and confidence levels.
+
+### Phase 5 — Validate and Refine
+1. Re-read the original research objective. Does the output answer it fully?
+2. Check for logical consistency.
+3. Check for completeness.
+4. Check for accuracy — are specific claims sourced?
+5. **Run a bias audit**.
+
+## Deep Thinking Reasoning Toolkit
+
+- **Chain of Thought (CoT)**: Break complex reasoning into explicit steps.
+- **Recursive Thought Expansion (RTE)**: When a step is ambiguous, expand it into its own sub-chain.
+- **Tree of Thought (ToT)**: Explore multiple reasoning paths, evaluate, prune.
+- **Graph of Thought (GoT)**: When reasoning is non-linear — ideas from different branches inform each other.
+- **Analysis of Competing Hypotheses (ACH)**: Evaluate evidence against multiple hypotheses systematically.
+- **Self-Consistency**: Generate the same conclusion via 3+ independent reasoning paths.
+- **Self-Reflection Loop**: Critique → Identify assumptions → Challenge → Refine.
+- **Adversarial Thinking (Red Team)**: Deliberately argue against your own conclusions.
+
+## Cognitive Bias Watchlist
+
+| Bias | How to Counter It |
+|------|-------------------|
+| **Confirmation bias** | Actively search for disconfirming evidence |
+| **Anchoring** | List questions before reading first source |
+| **Availability heuristic** | Use data and counts, not memorable anecdotes |
+| **Authority bias** | Even authoritative sources can be wrong — cross-validate |
+| **Satisficing** | Check: have I answered all original questions? |
+| **Groupthink** | Trace claims to origin — 5 blogs quoting 1 paper = 1 source |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Instead |
+|-------------|---------|
+| **Search-and-paste** | Pause and think after every search round |
+| **First-result bias** | Cross-reference with 2+ sources |
+| **Depth without breadth** | Always do Phase 1 before Phase 3 |
+| **Premature synthesis** | Complete at least 3 search rounds first |
+| **Citation-free claims** | If you can't cite it, flag it as uncertain |
+
+## Stopping Rules
+
+Stop researching when:
+- You've completed your planned search rounds (3–5).
+- New searches are returning information you've already seen (saturation).
+- You can confidently answer all your original questions.
+
+## References
+
+- `docs/agi/skills/session-discipline/SKILL.md` — for session tracking
+- `docs/agi/skills/instruction-adherence/SKILL.md` — for staying on objective

package/docs/agi/skills/endurance/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: endurance
+description: Strategies for long-running, complex, multi-stage autonomous agent execution. Enables token optimization, context preservation, and state stability over extremely long sessions.
+---
+
+# Endurance
+
+## Scope
+
+This Skill provides the architectural pattern for executing **Very Long-Running Agent Processes**. When an agent must solve a massive, multi-hour task (like a huge refactoring, generating an entire codebase, or doing comprehensive research), the standard context window will eventually fill up, leading to "context rot," hallucinations, and massive token costs.
+
+The **ENDURANCE** pattern solves this through Context Engineering, Dynamic State Management, and Auto-Prompting Workflows.
+
+## Core Principles
+
+1. **Context Quality > Context Quantity**: Even with 1M+ token windows, do not bloat the context. The "Lost in the Middle" phenomenon means models perform worst when critical data is buried. Keep the active context lean and relevant.
+2. **State Externalization**: The agent's memory must not live solely in the chat history. It must live in external artifacts.
+3. **The Endurance Loop (Auto-Prompting)**: Instead of one massive conversational thread, break the workflow into a chain of distinct contexts, linked by auto-generated prompts.
+
+## Implementation Methodology
+
+### 1. Externalized Memory & Working Notes
+- Maintain a `WORKING_NOTES.md` or `STATE.json` document.
+- **Compaction**: Before the context window grows too large (e.g., > 30-50 interactions), summarize the conversation history, write the key decisions and unresolved issues to the notes file, and **restart the context**.
+- **Just-In-Time Retrieval (Progressive Disclosure)**: Do not inject all codebase files into the system prompt. Use tools to fetch summaries, and drill down into specific files only when actively needed for the current step.
+
+### 2. Dynamic Skill & Tool Loading
+- **Avoid Prompt Inflation**: Only load the specific instructions (Skills) needed for the *current* sub-task. If you are doing UI design, load the CSS skill. If you are doing database migrations, load the DB skill. Do not load both at the same time.
+
+### 3. The Auto-Prompting Autonomous Workflow
+To maintain absolute stability and intelligence across a very long run, use this optimized loop:
+
+1. **Assess State:** Read the `WORKING_NOTES.md` and the master `task.md`.
+2. **Execute Step:** Perform the current sub-task using necessary tools.
+3. **Evaluator-Optimizer:** Self-evaluate the output. If it fails criteria, revise it immediately.
+4. **Generate Prompt Suggestions:** based on the completion of the current step, explicitly think about the 3 best possible *next* steps to advance the master task.
+5. **Auto-Select & Chain:** Select the single best prompt suggestion. 
+6. **Task Handoff (The Choke Point):** Write the selected prompt to a `NEXT_TASK.md` file or directly into the task queue, update the working notes, and optionally wipe the conversational context to start fresh on the new task, using the auto-selected prompt as the new system directive.
+
+### 4. Mitigating "Lost in the Middle"
+- When injecting necessary context (like a large file or research summary), place the most critical instructions and the specific task query at the **very beginning** and **very end** of the prompt.
+
+## Anti-Patterns to Avoid
+
+- **The Endless Thread**: Keeping a single conversation open for hundreds of tool calls. This leads to massive token costs (since every turn resends the entire history) and severe instruction drift.
+- **Context Hoarding**: Passing entire directory trees or irrelevant files into the context "just in case."
+- **Monolithic Prompts**: Trying to give the agent a single 50-step prompt. Break it down using the Endurance Loop.
+
+## Validation
+
+- Is the token usage stable across the different phases of the task?
+- Are decisions persisting correctly from Step 1 to Step 50? (If yes, your `WORKING_NOTES` are functioning properly).
+- Is the agent auto-suggesting its next prompt rather than waiting idly for the user?

package/docs/agi/skills/exploring-other-codebases/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: exploring-other-codebases
+description: Standard Operating Procedure for exploring unfamiliar, external, or third-party codebases. Use this skill when asked to review, audit, or integrate with a repository outside of your immediate context or training.
+---
+
+# Exploring Other Codebases
+
+## Scope
+
+This Skill provides a structured, high-speed methodology for exploring and mapping a completely unfamiliar external codebase without becoming overwhelmed by massive file counts or undocumented structures.
+
+## Triggers
+
+- "Explore this new repository"
+- "How does [External Library] work internally?"
+- "Let's look at the source code for [Dependency]"
+- Integrating a completely new third-party sub-module
+
+## Core Architecture Mapping
+
+When dealing with a new codebase, you cannot rely on knowing the directory conventions beforehand. You must discover them systematically.
+
+## Methodology
+
+### 1. Identify the Foundation (Entry Points)
+Before reading *any* logic code, you must locate and read the foundational setup files.
+- **Package Managers/Dependencies:** Search for `package.json`, `pom.xml`, `requirements.txt`, `Cargo.toml`, or `go.mod`. Use `view_file` on these to understand instantly what libraries the project relies on and what scripts it exposes (e.g., `npm run build`).
+- **Entry Points:** Look for `index.js`, `main.go`, `app.py`, or similar root-level execution files. 
+
+### 2. Map the High-Level Structure
+Do not manually walk every directory.
+- Use `list_dir` on the project root *once* to get the top-level folders.
+- Identify the most likely source code folder (typically `src/`, `lib/`, `app/`, or named after the project).
+
+### 3. Structural File Reading (Progressive Disclosure)
+When opening files in an unknown codebase, they may be overwhelmingly large or complex.
+- **MANDATORY**: Use `view_file_outline` to read the signature/structure of *any* file before using `view_file` to read its full contents. This allows you to map classes and exported functions instantly without flooding your context window with thousands of lines of implementation details.
+- If a file is over 1000 lines, use `grep_search` targeted *within* that file to find the specific function you need, rather than reading the whole file.
+
+### 4. Follow the Data (Trace Execution)
+If you need to understand a specific feature:
+1. Find the entry point or API route (e.g., `grep_search` for the route name).
+2. Trace the function calls. 
+3. Use `grep_search` to find where imported modules are defined if their location isn't obvious.
+
+## Anti-Patterns to Avoid
+
+- **The Breadth-First Blind Spot**: Using `list_dir` on every single sub-directory (like `node_modules` or `vendor`) before looking at `package.json` or `README.md`.
+- **Context Flooding**: Using `view_file` on 5 different core files simultaneously in an unknown codebase, completely destroying your context window limits, instead of using `view_file_outline`.
+- **Assuming Conventions**: Assuming an external Node.js app uses Express just because another project does. Always check the dependency file first.
+
+## Validation
+
+- Did you check `package.json` (or equivalent) before exploring the source directories?
+- Did you use `view_file_outline` to map large files instead of reading them blindly?
+- Can you summarize the high-level architecture (entry point, key directories, main framework) to the user?

package/docs/agi/skills/instruction-adherence/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: instruction-adherence
+description: "Use when instruction drift is likely: multi-step tasks, mid-task detours (tooling upgrades), or when agents must consult Skills and re-anchor repeatedly. Triggers: 'stay on track', 'follow instructions', 'resume main task', 'detour', 'intermediate task done'."
+---
+
+# Skill: Instruction Adherence (Stay On Track)
+
+## Scope
+
+This Skill is about reliably following instructions across:
+- Multiple instruction sources (system/developer/mode files, repo docs, user request)
+- Memory sources (Skills registry, sessions, lessons/patterns)
+- Multi-step execution where detours happen (e.g., "improve CLI tooling" mid-stream)
+
+## Inputs
+
+- The current user request (objective + success criteria)
+- The active mode/persona (if any)
+- Repo guardrails (AGENTS.md, testing commands)
+
+## Procedure
+
+### 1) Capture an "Instruction Snapshot" (mandatory)
+
+In your working notes, write a short snapshot:
+- **Objective**: 1 sentence
+- **Must do**: 3–7 bullets
+- **Must not**: 3–7 bullets
+- **Evidence**: what output/tests/checks will prove done
+
+This becomes the "north star" when you get interrupted.
+
+### 2) Run the memory retrieval ritual (Skills → Docs)
+
+- Skills: scan `docs/agi/skills/` and follow any matching SOP.
+- Docs: check `AGENTS.md` and relevant documentation.
+
+### 3) Build a "Task Ledger" with explicit parent/child tasks
+
+Use a structured task list that prevents detours from becoming the main task:
+- Parent task: user's objective
+- Child tasks: discovery → implement → validate → document
+- If a detour is required (e.g., CLI tooling improvement), make it a **child task** with:
+  - **Entry criteria** (why it's needed)
+  - **Exit criteria** (what "done" means)
+  - **Return step** (the exact next step to resume)
+
+### 4) The Re-anchor loop (run after every subtask)
+
+After any meaningful milestone (or after 3–5 tool calls):
+- Re-read the Instruction Snapshot
+- Mark completed tasks
+- Confirm the next step is still on the parent objective
+- If you drifted, explicitly choose to:
+  - Resume parent objective, or
+  - Create a follow-up and stop the detour
+
+### 5) "Detour complete → resume" protocol
+
+When an intermediate task (like CLI tooling improvement) is completed:
+1. Record a one-paragraph summary + evidence in the session notes.
+2. Add/update a Skill or Lesson if it will recur.
+3. Immediately take the "Return step" you wrote in the task ledger.
+
+## Validation (evidence checklist)
+
+- Working notes contain an Instruction Snapshot.
+- Task ledger clearly separates parent objective vs detours.
+- At least one re-anchor checkpoint is recorded.
+- Session summary includes an **Instruction Reflection**:
+  - What instructions helped?
+  - What was missing/wrong?
+  - What durable doc/agent update was made?

package/docs/agi/skills/jsgui3-activation-debug/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: jsgui3-activation-debug
+description: Debug jsgui3 client-side activation issues. Use when SSR renders but clicks don't work, this.dom.el is null, or you see Missing context.map_Controls / activation failures.
+---
+
+# jsgui3 Activation Debug
+
+## Triggers
+
+- "jsgui3", "clicks don't work", "activation", "Missing context.map_Controls"
+
+## Scope
+
+- Diagnose "renders but no interactivity" failures
+- Ensure client bundle is current when tests run in a browser
+- Add a minimal check script when behavior is unclear
+
+## Inputs
+
+- Which server/route/control is affected
+- Whether the issue reproduces in E2E (Puppeteer/Playwright)
+- Whether client bundling is involved
+
+## Procedure
+
+1. Confirm this is an activation issue, not just CSS/DOM.
+   - View the page source — if the HTML looks correct, it's likely activation.
+   - If the HTML is wrong, it's an SSR bug (different skill).
+
+2. Follow the documented activation flow and look for the canonical signatures:
+   - `data-jsgui-id` attributes on SSR elements
+   - `data-jsgui-type` for constructor mapping
+   - Client bundle loading correctly in browser Network tab
+
+3. Check the client bundle is up to date:
+   - If using bundled client JS, ensure it was rebuilt after any control changes.
+   - The server's bundler in `serve-factory.js` handles this automatically in most cases.
+
+4. Check `activate()` implementation:
+   - Is `super.activate()` being called?
+   - Is `this.dom.el` available at the time of activation?
+   - Are event listeners being attached in `activate()`, not in the constructor?
+
+5. If unclear, create a minimal reproduction check:
+   ```javascript
+   // Quick check: does the control load and render?
+   const Server = require('./server');
+   const s = new Server({port: 0});
+   // ... mount the control, start, check response
+   ```
+
+## Common Error Messages
+
+- **`Missing context.map_Controls for type <X>`**: SSR said the element is type X, but the client doesn't have a constructor registered. Client falls back to generic `Control`.
+- **`Missing context.map_Controls for type undefined`**: Often corresponds to tags where `data-jsgui-type` is intentionally not emitted (html/head/body). Usually log noise.
+- **`&&& no corresponding control`**: Emitted during pre-activation when DOM contains text nodes that don't correspond to a control entry. Often benign whitespace.
+
+## Validated Patterns
+
+### Pattern: Manual DOM Query in `activate()`
+When standard control field linking is insufficient, explicitly querying the DOM in `activate()` is a robust fallback:
+
+```javascript
+activate() {
+  if (this.__active) return;
+  this.__active = true;
+
+  const el = this.dom?.el;
+  if (!el) return;
+
+  // 1. Read config from data attributes
+  this.initial_width = parseInt(el.dataset.initialWidth, 10);
+
+  // 2. Query explicitly for child elements
+  this._expand_handle_el = el.querySelector("[data-expand-handle]");
+  
+  // 3. Bind events
+  if (this._expand_handle_el) {
+    this._expand_handle_el.addEventListener("click", this._handle_expand.bind(this));
+  }
+}
+```
+
+## Anti-Patterns to Avoid
+
+- **Blindly Editing CSS**: Assuming a control isn't working because of z-index or pointer-events, when the real issue is that the JS `activate()` method never fired on the client.
+- **Skipping Build**: Making changes to control logic and running E2E tests without rebuilding the client bundle first, leading to false negatives.
+
+## References
+
+- jsgui3 understanding: `docs/agi/skills/understanding-jsgui3/SKILL.md`
+- Comprehensive documentation: `docs/comprehensive-documentation.md`
+- Controls development guide: `docs/controls-development.md`
+- Server source: `server.js`, `serve-factory.js`