AI Workflow & Prompt Engine

Learn how NutEgg's modular workflow engine orchestrates content extraction, summary-based egg routing, instruction-driven analysis, and user-customizable prompts.

The Two-Stage Architecture

Rather than running a single monolithic prompt, NutEgg uses a Two-Stage Architecture designed for token efficiency, high extraction precision, and complete user control:

                    ┌───────────────────────────────┐
                    │      Captured Web Content     │
                    │   (Article / YouTube / Tweet) │
                    └───────────────┬───────────────┘
                                    │
                                    ▼
       ===========================================================
       STAGE 1: Content & Discussion Analysis + Egg Routing
       ===========================================================
            │                                             │
            ├─► Content Analysis                          ├─► Discussion Analysis
            │   (Is content >30k chars?)                  │   (When 💬 Discussion enabled
            │    ├── No  ──► [content-analysis.md]        │    & comments captured)
            │    └── Yes ──► Chunks + [aggregate-         │    ├── [discussion-analysis.md]
            │                content.md]                  │    └── [aggregate-discussion.md]
            │                                             │
            └──────────────────────┬──────────────────────┘
                                   │
                                   ▼
        Produces: Title Verdict, 3-Bullet Summary, Mind Map,
        Timestamped Q&A, and Discussion Topics/Stances
                                   │
                                   ▼
                          [egg-routing.md]
          (Routes matched eggs from _index.md using the
           concise Stage 1 summary instead of raw content)
                                    │
                                    ▼
       ===========================================================
       INTERACTIVE CHOICE / EXECUTION MODE (Chrome Extension)
       ===========================================================
                                    │
                        Which mode is selected?
                                    │
            ┌───────────────────────┼───────────────────────┐
            ▼                       ▼                       ▼
     [Standalone Mode]         [🌞 Full Mode]      [🌛 Preview Summary]
     Obsidian is offline.      Auto-proceeds to    User reviews matched eggs:
     Runs Stage 1 in Chrome    Stage 2 with all    ├── "Collect Nut Only"
     with user's API key.      matched eggs.       └── Add/remove eggs ──► Proceed
     (Fast reading & Q&A)           │                       │
            │                       └───────────┬───────────┘
            ▼                                   ▼
    Results in Side Panel      ===========================================================
    (No Stage 2 analysis)    STAGE 2: Per-Egg Instruction-Driven Analysis
                               ===========================================================
                                                │
                                   For each confirmed egg (1 or N):
                                                │
                                                ▼
                                        [egg-analysis.md]
                                  (Extract candidate knowledge entries
                                   & key questions scoped to this egg)
                                                │
                                                ▼
                                  (Answers + extracted entries + reading action)
                                                │
                                                ▼
                                     Results returned to Popup
                                     (Ready to Save Nut & Eggs)

💡 Why Summary-Based Routing?

Routing eggs using the Stage 1 summary instead of full raw articles or multi-hour video transcripts saves tens of thousands of tokens per run and improves routing accuracy by focusing on distilled, high-signal semantic themes.

The side panel’s cross-tab indicator shows running analyses and unread completed results in the current Chrome window. Click it to list tabs and switch directly to their results or progress. Results become read when their analysis is visible in the active tab. Tracking lasts while the panel stays open and resets when it closes.

Hatch archives the original analysis and appends approved entries to # Unprocessed. Merge runs at 20 pending entries or on demand to assemble fragments and deduplicate claims while preserving sources, caveats, examples, and disagreements. Stage 2 never receives the Knowledge tree, so the recommendation assesses relevance and substance rather than novelty.

The 🍃 Knowledge section option and the Egg Analysis dropdown share one setting for the current browser tab: 🥚 Analysis only switches Knowledge off, and 🍃 Include knowledge switches it on. Switching dropdown choices updates the setting and button label without auto-triggering an AI call—click the button to analyze. When switching to Include Knowledge for an egg analyzed previously without knowledge entries, NutEgg reruns Stage 2 rather than simply showing the cached answer-only result. Include knowledge is the initial default; your last choice becomes the default for tabs without analysis. Turning the option off does not hide previously generated entries or prevent saving them. Turning Knowledge off disables entries for every selected egg. Turning it on allows entries only for eggs that permit them: Generate Knowledge Entries: no or an opt-out in the egg’s Action Guide takes priority. Key answers and reading recommendations remain available either way. Analysis does not save entries; 🐣 Hatch Egg saves generated entries to egg files.

Workflow Modes

Mode	Behavior	Best Used For
📱 Standalone Mode	Runs Stage 1 content analysis directly in Chrome (when Obsidian is offline or closed). Produces verdicts, 3-sentence summaries, mind maps with clickable timestamps, and interactive video Q&A with timestamp jumping. Skips Stage 2 egg analysis.	Fast web and video reading, quick comprehension, or when you don't need note archiving.
🌞 Full Mode	Runs Stage 1 content analysis, routes eggs automatically via `_index.md`, and immediately executes Stage 2 egg analysis in one uninterrupted pass.	Everyday reading and quick captures when you trust automatic egg matching.
🌛 Preview Summary	Runs Stage 1 content analysis, then pauses in the popup. Shows matched eggs alongside your vault's full egg list. You can add/remove eggs, proceed with knowledge comparison, or click Collect Nut Only.	Deep research, ambiguous topics, or when you only want a quick summary without updating egg knowledge trees.

AI Execution & Credential Protocol

Regardless of whether you choose Full Mode or Preview Summary, NutEgg separates workflow orchestration from credential storage and AI inference:

Connected API Mode (Default): Obsidian coordinates prompt template injection and knowledge comparison, but sends inference requests to Chrome over an authenticated WebSocket (/execution/socket). Chrome runs the LLM call with its local API key and sends the authenticated result back. Your API key never leaves Chrome.
Shared Subscription Mode: Obsidian coordinates the workflow and directly executes AI calls locally using official developer CLI tools (codex, claude, agy) or direct ChatGPT OAuth sign-in. All connected Chrome profiles share this subscription without needing an API key.

Workflow Files in Your Vault

NutEgg seeds its prompt templates into nutegg/_workflow/ inside your vault:

1. Shared Fragments (Injected into other prompts)

shared-output-rules.md: Grounding directive (source content as sole truth) and multi-lingual output language reference rules. Injected as {{shared_output_rules}}.
content-task-default.md: Core task instructions for title verdicts, 3-bullet summaries, and mind maps with clickable timestamps. Injected as {{content_task_default}}.

2. Content Capture & Comparison Pipeline

content-analysis.md: Stage 1 content summary, anti-clickbait verdict, interactive mind map with clickable timestamps, and custom question answers with timestamp citations.
egg-routing.md: Matches Stage 1 summaries against egg descriptions in _index.md to select candidate eggs.
egg-analysis.md: Stage 2 per-egg extraction of candidate knowledge entries and key question answers scoped to one egg's instructions.
Worth Reading If and Skip If guide full reading, highlights, summary sufficient, skip, or uncertain. Useful answers remain saveable regardless of the recommendation.
aggregate-content.md & aggregate-egg.md: Long-content (>30k characters) aggregation. Stage 2 combines only answer drafts, recommendation notes, and coverage; extracted entries remain in source order until merge.

3. Discussion Analysis (Stage 1)

Discussion analysis executes as part of Stage 1 content analysis when the 💬 Discussion section is enabled in Extension Options or popup Analysis Sections, and the page extractor captures reader comments or social replies (e.g. YouTube comments, Twitter replies, Reddit/forum threads, Bilibili comments, or Zhihu answers).

discussion-analysis.md: Analyzes comments in batches to extract 3–5 core debating topics, classify commenter stances (agree, disagree, mixed, neutral, unclear), and highlight valuable firsthand experience supplements or corrections (supplement: true).
aggregate-discussion.md: Merges and synthesizes topics and stance distributions across multi-batch comment threads for large forums or video comment sections.

Context Flow: Analyzed discussion summaries and evidence items are returned in the Stage 1 result and feed directly into custom Q&A or forum body analysis (crucial for discussion-centric pages or videos without transcripts). They are also forwarded as context signals into Stage 2 egg-analysis.md so eggs can evaluate community feedback alongside the source content.

4. Interactive & Maintenance Workflows

follow-up.md: Interactive natural-language Q&A in the side panel with prior conversation history and clickable video timestamp jumping.
merge-unprocessed.md: Triggered manually or automatically at 20+ pending entries to organize and nest raw items into # Knowledge.
localize-egg.md: Translates new egg templates into foreign languages while preserving English structural headings.

Safe Customization Guidelines

⚠️ What to Preserve

You are free to customize prompt tone, perspective, and depth. However, you must preserve:

All {{placeholder}} tags (e.g. {{content}}, {{knowledge_tree}}, {{title}}).
Exact JSON output keys (e.g. titleVerdict, extractedEntries, mindMap) so the parser can deserialize the response.
Structural headings (# Knowledge, # Unprocessed) in markdown outputs.

Conflict-Free Updates & Reset

When NutEgg updates to a newer version:

Unedited Prompts: Automatically updated to the latest built-in version.
Customized Prompts: Your edits are never overwritten. NutEgg writes [filename].new.md alongside your file so you can review new additions at your own pace.
Factory Reset ("Use Defaults"): Need a fresh start? In Obsidian Settings → NutEgg, click Use Defaults. All existing prompts are safely backed up to nutegg/_workflow/_backup/<timestamp>/ and pristine factory defaults are restored.