{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Forge Seeds AI Agent Specification",
  "version": "1.0.0",
  "metadata": {
    "name": "Forge Seeds",
    "version": "1.0.0",
    "description": "AI STEM Flashcards & Spaced Repetition Engine with Dynamic Lexicon Vault",
    "domain": "https://forgeseeds.com",
    "author": "ForgeBoro",
    "specVersion": "2026.1",
    "documentationUrl": "https://forgeseeds.com/help.html",
    "specJsonUrl": "https://forgeseeds.com/agent-spec.json",
    "runtimeWindowProperty": "window.__SEEDS_AGENT_SPEC__"
  },
  "automationProtocol": {
    "domConvention": {
      "toolAttribute": "data-tool",
      "actionAttribute": "data-action",
      "selectorPattern": "[data-tool=\"{tool}\"][data-action=\"{action}\"]"
    },
    "runtimeController": {
      "object": "window.__SEEDS_AGENT_SPEC__",
      "methods": [
        "getSpec()",
        "getSelector(tool, action)",
        "getAvailableActions()",
        "executeAction(tool, action, options)"
      ]
    }
  },
  "tools": {
    "navigation": {
      "description": "Application navigation and route controls",
      "actions": {
        "open-terms": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-terms\"]",
          "description": "Navigate to All Terms lexicon view",
          "shortcut": "Alt+T"
        },
        "open-glossaries": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-glossaries\"]",
          "description": "Navigate to My Glossaries collection",
          "shortcut": "Alt+G"
        },
        "open-community": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-community\"]",
          "description": "Navigate to Community Glossaries",
          "shortcut": "Alt+C"
        },
        "open-topic-explorer": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-topic-explorer\"]",
          "description": "Open Magic Topic Explorer modal",
          "shortcut": "Alt+E"
        },
        "open-graph": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-graph\"]",
          "description": "Navigate to 2D Knowledge Graph view"
        },
        "open-print": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-print\"]",
          "description": "Open print / PDF layout view"
        },
        "open-flashcards-print": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-flashcards-print\"]",
          "description": "Open printable flashcards sheet layout view (uniform 8 cards/page PDF preview)"
        },
        "open-about": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-about\"]",
          "description": "Navigate to About Seeds page"
        },
        "open-help": {
          "selector": "[data-tool=\"navigation\"][data-action=\"open-help\"]",
          "description": "Open interactive Help and Documentation modal",
          "shortcut": "?"
        },
        "toggle-menu": {
          "selector": "[data-tool=\"navigation\"][data-action=\"toggle-menu\"]",
          "description": "Toggle mobile navigation drawer"
        },
        "back-to-glossaries": {
          "selector": "[data-tool=\"navigation\"][data-action=\"back-to-glossaries\"]",
          "description": "Navigate back from filtered terms to glossary list"
        }
      }
    },
    "theme": {
      "description": "Visual aesthetic and theme controls",
      "actions": {
        "toggle-palette": {
          "selector": "[data-tool=\"theme\"][data-action=\"toggle-palette\"]",
          "description": "Cycle visual color palette (Default, Neo-Mint, Cyber-Orchid, etc.)",
          "shortcut": "Alt+P"
        },
        "toggle-dark-mode": {
          "selector": "[data-tool=\"theme\"][data-action=\"toggle-dark-mode\"]",
          "description": "Toggle light and dark mode",
          "shortcut": "Alt+D"
        }
      }
    },
    "search": {
      "description": "Lexicon search and filtering",
      "actions": {
        "search-terms": {
          "selector": "[data-tool=\"search\"][data-action=\"search-terms\"]",
          "description": "Filter terms and definitions by query string",
          "shortcut": "/"
        },
        "clear-search": {
          "selector": "[data-tool=\"search\"][data-action=\"clear-search\"]",
          "description": "Clear current search filter"
        },
        "filter-tag": {
          "selector": "[data-tool=\"search\"][data-action=\"filter-tag\"]",
          "description": "Filter terms by selected glossary tag or orphan terms status (__ORPHAN_TERMS__)",
          "params": { "tag": "string" }
        }
      }
    },
    "terms": {
      "description": "Term CRUD, definition editing, and jump navigation",
      "actions": {
        "create-term": {
          "selector": "[data-tool=\"terms\"][data-action=\"create-term\"]",
          "description": "Open term creation modal",
          "shortcut": "Alt+N"
        },
        "edit-term": {
          "selector": "[data-tool=\"terms\"][data-action=\"edit-term\"]",
          "description": "Open term edit modal for targeted term",
          "params": { "termId": "string" }
        },
        "delete-term": {
          "selector": "[data-tool=\"terms\"][data-action=\"delete-term\"]",
          "description": "Delete targeted term from personal vault",
          "params": { "termId": "string" }
        },
        "toggle-expand": {
          "selector": "[data-tool=\"terms\"][data-action=\"toggle-expand\"]",
          "description": "Expand/collapse long definition accordion card",
          "params": { "termId": "string" }
        },
        "jump-term": {
          "selector": "[data-tool=\"terms\"][data-action=\"jump-term\"]",
          "description": "Jump to internal cross-referenced term card",
          "params": { "termId": "string" }
        },
        "generate-definition": {
          "selector": "[data-tool=\"terms\"][data-action=\"generate-definition\"]",
          "description": "Trigger AI definition regeneration",
          "params": { "termId": "string" }
        },
        "auto-cross-reference": {
          "selector": "[data-tool=\"terms\"][data-action=\"auto-cross-reference\"]",
          "description": "Scan long definition and inject cross-reference hyperlinks",
          "params": { "termId": "string" }
        },
        "open-term-menu": {
          "selector": "[data-tool=\"terms\"][data-action=\"open-term-menu\"]",
          "description": "Open contextual action menu for a term card",
          "params": { "termId": "string" }
        }
      }
    },
    "glossary": {
      "description": "Glossary collection management and study launcher",
      "actions": {
        "create-glossary": {
          "selector": "[data-tool=\"glossary\"][data-action=\"create-glossary\"]",
          "description": "Open glossary creation modal"
        },
        "edit-glossary": {
          "selector": "[data-tool=\"glossary\"][data-action=\"edit-glossary\"]",
          "description": "Edit glossary metadata, title, and cover",
          "params": { "glossaryId": "string" }
        },
        "delete-glossary": {
          "selector": "[data-tool=\"glossary\"][data-action=\"delete-glossary\"]",
          "description": "Delete glossary collection",
          "params": { "glossaryId": "string" }
        },
        "clone-glossary": {
          "selector": "[data-tool=\"glossary\"][data-action=\"clone-glossary\"]",
          "description": "Clone community glossary to personal library",
          "params": { "glossaryId": "string" }
        },
        "filter-by-glossary": {
          "selector": "[data-tool=\"glossary\"][data-action=\"filter-by-glossary\"]",
          "description": "Filter term lexicon to specific glossary tags",
          "params": { "glossaryTitle": "string" }
        },
        "generate-terms": {
          "selector": "[data-tool=\"glossary\"][data-action=\"generate-terms\"]",
          "description": "Open AI generator to append terms to glossary",
          "params": { "glossaryId": "string" }
        },
        "toggle-public-status": {
          "selector": "[data-tool=\"glossary\"][data-action=\"toggle-public-status\"]",
          "description": "Toggle public community sharing status of a glossary",
          "params": { "glossaryId": "string" }
        },
        "open-glossary-menu": {
          "selector": "[data-tool=\"glossary\"][data-action=\"open-glossary-menu\"]",
          "description": "Open contextual action menu for a glossary card",
          "params": { "glossaryId": "string" }
        },
        "open-flashcards-page": {
          "selector": "[data-tool=\"glossary\"][data-action=\"open-flashcards-page\"]",
          "description": "Navigate to canonical shareable flashcards subpage (/flashcards/[glossaryId])",
          "params": { "glossaryId": "string" }
        },
        "copy-flashcards-link": {
          "selector": "[data-tool=\"glossary\"][data-action=\"copy-flashcards-link\"]",
          "description": "Copy direct shareable flashcards link to clipboard",
          "params": { "glossaryId": "string" }
        },
        "print-flashcards": {
          "selector": "[data-tool=\"glossary\"][data-action=\"print-flashcards\"]",
          "description": "Download or print uniform flashcards PDF (8 cards/page) for the glossary",
          "params": { "glossaryId": "string" }
        }
      }
    },
    "study": {
      "description": "Flashcards spaced repetition study mode",
      "actions": {
        "open-flashcards": {
          "selector": "[data-tool=\"study\"][data-action=\"open-flashcards\"]",
          "description": "Launch flashcard study modal for glossary",
          "params": { "glossaryId": "string" }
        },
        "flip-card": {
          "selector": "[data-tool=\"study\"][data-action=\"flip-card\"]",
          "description": "Flip active flashcard to reveal back definition",
          "shortcut": "Space"
        },
        "rate-srs-hard": {
          "selector": "[data-tool=\"study\"][data-action=\"rate-srs-hard\"]",
          "description": "Rate flashcard recall as Hard (Score 1)",
          "shortcut": "1"
        },
        "rate-srs-good": {
          "selector": "[data-tool=\"study\"][data-action=\"rate-srs-good\"]",
          "description": "Rate flashcard recall as Good (Score 3)",
          "shortcut": "2"
        },
        "rate-srs-easy": {
          "selector": "[data-tool=\"study\"][data-action=\"rate-srs-easy\"]",
          "description": "Rate flashcard recall as Easy (Score 5)",
          "shortcut": "3"
        },
        "shuffle-cards": {
          "selector": "[data-tool=\"study\"][data-action=\"shuffle-cards\"]",
          "description": "Shuffle study deck cards"
        },
        "close-study": {
          "selector": "[data-tool=\"study\"][data-action=\"close-study\"]",
          "description": "Exit flashcards modal",
          "shortcut": "Esc"
        }
      }
    },
    "quiz": {
      "description": "Adaptive 4-option multiple-choice quizzes with AI distractors",
      "actions": {
        "open-quiz": {
          "selector": "[data-tool=\"quiz\"][data-action=\"open-quiz\"]",
          "description": "Launch quiz mode modal for glossary",
          "params": { "glossaryId": "string" }
        },
        "select-option": {
          "selector": "[data-tool=\"quiz\"][data-action=\"select-option\"]",
          "description": "Select multiple-choice answer option (1-4)",
          "shortcut": "1, 2, 3, 4"
        },
        "next-question": {
          "selector": "[data-tool=\"quiz\"][data-action=\"next-question\"]",
          "description": "Advance to next quiz question",
          "shortcut": "Enter"
        },
        "restart-quiz": {
          "selector": "[data-tool=\"quiz\"][data-action=\"restart-quiz\"]",
          "description": "Restart quiz session with newly shuffled questions"
        },
        "close-quiz": {
          "selector": "[data-tool=\"quiz\"][data-action=\"close-quiz\"]",
          "description": "Exit quiz modal",
          "shortcut": "Esc"
        }
      }
    },
    "ai": {
      "description": "Gemini AI concept explorer and batch term generation",
      "actions": {
        "open-topic-explorer": {
          "selector": "[data-tool=\"ai\"][data-action=\"open-topic-explorer\"]",
          "description": "Open topic explorer modal",
          "shortcut": "Alt+E"
        },
        "generate-terms": {
          "selector": "[data-tool=\"ai\"][data-action=\"generate-terms\"]",
          "description": "Trigger AI batch term generation"
        }
      }
    },
    "data": {
      "description": "Data import, export, and backup operations",
      "actions": {
        "toggle-data-menu": {
          "selector": "[data-tool=\"data\"][data-action=\"toggle-data-menu\"]",
          "description": "Toggle Data Management sidebar submenu"
        },
        "export-json": {
          "selector": "[data-tool=\"data\"][data-action=\"export-json\"]",
          "description": "Download JSON backup file"
        },
        "export-docx": {
          "selector": "[data-tool=\"data\"][data-action=\"export-docx\"]",
          "description": "Download formatted Word .docx document"
        },
        "import-json": {
          "selector": "[data-tool=\"data\"][data-action=\"import-json\"]",
          "description": "Import terms and glossaries from JSON"
        },
        "wipe-all-data": {
          "selector": "[data-tool=\"data\"][data-action=\"wipe-all-data\"]",
          "description": "Wipe all user terms (requires confirmation)"
        }
      }
    }
  },
  "keyboardShortcuts": [
    { "key": "?", "label": "?", "description": "Open Help & Documentation Modal", "category": "General" },
    { "key": "Escape", "label": "Esc", "description": "Close active modal or dismiss flyout", "category": "General" },
    { "key": "/", "label": "/", "description": "Focus Lexicon Search bar", "category": "Navigation" },
    { "key": "Alt+t", "label": "Alt + T", "description": "Switch to All Terms lexicon view", "category": "Navigation" },
    { "key": "Alt+g", "label": "Alt + G", "description": "Switch to My Glossaries collection", "category": "Navigation" },
    { "key": "Alt+c", "label": "Alt + C", "description": "Switch to Community Glossaries", "category": "Navigation" },
    { "key": "Alt+e", "label": "Alt + E", "description": "Open Magic Topic Explorer", "category": "Navigation" },
    { "key": "Alt+n", "label": "Alt + N", "description": "Create new Term or Glossary", "category": "Authoring" },
    { "key": "Alt+p", "label": "Alt + P", "description": "Switch color palette theme", "category": "General" },
    { "key": "Alt+d", "label": "Alt + D", "description": "Toggle light / dark mode", "category": "General" },
    { "key": "Space", "label": "Space", "description": "Flip flashcard (in Study Mode)", "category": "Study & Quiz" },
    { "key": "1", "label": "1", "description": "Rate Hard in Study / Select Option 1 in Quiz", "category": "Study & Quiz" },
    { "key": "2", "label": "2", "description": "Rate Good in Study / Select Option 2 in Quiz", "category": "Study & Quiz" },
    { "key": "3", "label": "3", "description": "Rate Easy in Study / Select Option 3 in Quiz", "category": "Study & Quiz" },
    { "key": "4", "label": "4", "description": "Select Option 4 in Quiz", "category": "Study & Quiz" },
    { "key": "Enter", "label": "Enter", "description": "Next Question in Quiz Mode", "category": "Study & Quiz" }
  ],
  "apiEndpoints": [
    {
      "method": "GET",
      "path": "/api/terms",
      "description": "Fetch all terms owned by the authenticated user",
      "authenticated": true,
      "responseBody": "Term[]"
    },
    {
      "method": "POST",
      "path": "/api/terms",
      "description": "Create a new term with definitions, tags, and aliases",
      "authenticated": true,
      "requestBody": "{ name: string, shortDef?: string, longDef?: string, tags?: string[], aliases?: string[], distractors?: string[] }",
      "responseBody": "Term"
    },
    {
      "method": "PUT",
      "path": "/api/terms/[termId]",
      "description": "Update an existing term",
      "authenticated": true,
      "requestBody": "Partial<Term>",
      "responseBody": "Term"
    },
    {
      "method": "DELETE",
      "path": "/api/terms/[termId]",
      "description": "Delete an existing term",
      "authenticated": true,
      "responseBody": "{ success: boolean }"
    },
    {
      "method": "POST",
      "path": "/api/terms/[termId]/generate",
      "description": "Trigger Gemini AI generation of long definition and distractors",
      "authenticated": true,
      "responseBody": "{ longDef: string, distractors: string[] }"
    },
    {
      "method": "GET",
      "path": "/api/glossaries",
      "description": "Fetch user glossaries and public community glossaries",
      "authenticated": false,
      "responseBody": "{ user: Glossary[], public: Glossary[] }"
    },
    {
      "method": "POST",
      "path": "/api/glossaries",
      "description": "Create a new glossary collection",
      "authenticated": true,
      "requestBody": "{ title: string, description?: string, filterTags: string[], isPublic?: boolean }",
      "responseBody": "Glossary"
    },
    {
      "method": "POST",
      "path": "/api/glossaries/[glossaryId]/clone",
      "description": "Clone a community glossary and its terms into user vault",
      "authenticated": true,
      "responseBody": "{ success: boolean, termsCloned: number }"
    },
    {
      "method": "POST",
      "path": "/api/topic/explore",
      "description": "Validate a STEM or business topic and generate starter concepts",
      "authenticated": true,
      "requestBody": "{ topic: string }",
      "responseBody": "{ isStem: boolean, isStemOrRelated: boolean, category: string, concepts: Array<{ name: string, shortDef: string, tags: string[] }> }"
    },
    {
      "method": "GET",
      "path": "/api/export",
      "description": "Download JSON backup of terms and glossaries",
      "authenticated": true,
      "responseBody": "application/json"
    },
    {
      "method": "GET",
      "path": "/api/export/docx",
      "description": "Compile and download formatted Word document (.docx)",
      "authenticated": true,
      "responseBody": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    },
    {
      "method": "GET",
      "path": "/api/glossaries/[glossaryId]/flashcards/pdf",
      "description": "Download uniform flashcards PDF (8 cards/page, 3.6\" x 2.3\") for glossary terms",
      "authenticated": true,
      "responseBody": "application/pdf"
    },
    {
      "method": "GET",
      "path": "/api/export/flashcards/pdf",
      "description": "Download uniform flashcards PDF filtered by query tags or all terms",
      "authenticated": true,
      "responseBody": "application/pdf"
    },
    {
      "method": "POST",
      "path": "/api/import",
      "description": "Import terms and glossaries from JSON payload",
      "authenticated": true,
      "requestBody": "{ terms: Term[], glossaries?: Glossary[] }",
      "responseBody": "{ count: number, glossaryCount: number }"
    }
  ],
  "dataModels": {
    "Term": {
      "id": "string",
      "name": "string",
      "shortDef": "string",
      "longDef": "string",
      "tags": "string[]",
      "aliases": "string[]",
      "distractors": "string[]",
      "srs": {
        "interval": "number",
        "repetition": "number",
        "easeFactor": "number",
        "nextReview": "number",
        "masteryLevel": "Unplanted | Seeded | Sprouting | Deep Rooted"
      },
      "authorId": "string",
      "createdAt": "number",
      "updatedAt": "number"
    },
    "Glossary": {
      "id": "string",
      "title": "string",
      "description": "string",
      "filterTags": "string[]",
      "isPublic": "boolean",
      "authorId": "string",
      "authorName": "string",
      "createdAt": "number"
    },
    "MasteryLevels": [
      { "name": "Unplanted", "stage": 0, "icon": "🌱", "description": "Not yet reviewed or score < 2" },
      { "name": "Seeded", "stage": 1, "icon": "🌿", "description": "Initial review complete (1-2 successful recalls)" },
      { "name": "Sprouting", "stage": 2, "icon": "🌲", "description": "Consistent recall (3-4 reviews, interval > 6 days)" },
      { "name": "Deep Rooted", "stage": 3, "icon": "🌳", "description": "High retention mastery (repetition >= 5, interval >= 21 days)" }
    ]
  }
}