{
  "schemaVersion": "1.0",
  "item": {
    "slug": "librarian",
    "name": "librarian companion",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/nonlinear/librarian",
    "canonicalUrl": "https://clawhub.ai/nonlinear/librarian",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/librarian",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=librarian",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "librarian.py",
      "README.md",
      "package.json",
      "SKILL.md",
      "librarian.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/librarian"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/librarian",
    "agentPageUrl": "https://openagent3.xyz/skills/librarian/agent",
    "manifestUrl": "https://openagent3.xyz/skills/librarian/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/librarian/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Librarian - Semantic Research Skill",
        "body": "Version: 2.0.0 (Protocol-driven)\nStatus: 🚧 Development\nArchitecture: Sandwich (🎤 Skill → 👷 Wrapper → ⚙️ Python)"
      },
      {
        "title": "What This Skill Does",
        "body": "Search your book library using natural language. Ask questions like \"What does Graeber say about debt?\" and get precise citations with page numbers."
      },
      {
        "title": "Protocol Flow",
        "body": "flowchart TB\n    TRIGGER[\"🎤 Trigger + context\"]:::ready\n    TRIGGER --> METADATA[\"👷 Load metadata 1️⃣\"]:::ready\n    METADATA --> CHECK{\"👷 Metadata exists?\"}:::ready\n    \n    CHECK -->|No| ERROR[\"🎤 🤚 No metadata found:<br>Run librarian index 5️⃣\"]:::ready\n    CHECK -->|Yes| INFER{\"🎤 Infer scope? 2️⃣\"}:::ready\n    \n    INFER -->|confidence lower than 75%| CLARIFY[\"🎤 🤚 Say it again? 5️⃣\"]:::ready\n    INFER -->|confidence higher than 75%| BUILD[\"👷 Build command 3️⃣\"]:::ready\n    \n    BUILD --> CHECK_SYSTEM{\"⚙️ System working?\"}:::ready\n    \n    CHECK_SYSTEM -->|No| BROKEN[\"🎤 🤚 System is broken 5️⃣\"]:::ready\n    CHECK_SYSTEM -->|Yes| EXEC[\"⚙️ Run python script with flags\"]:::ready\n    \n    EXEC --> JSON[\"⚙️ Return JSON\"]:::ready\n    JSON --> CHECK_RESULTS{\"👷 Results found?\"}:::ready\n    \n    CHECK_RESULTS -->|No| EMPTY[\"🎤 🤚 No results found 5️⃣\"]:::ready\n    CHECK_RESULTS -->|Yes| FORMAT[\"🎤 Format output 4️⃣\"]:::ready\n    \n    FORMAT --> RESPONSE[\"🎤 Librarian response\"]:::ready\n\n    classDef ready fill:#c8e6c9,stroke:#81c784,color:#2e7d32\n\nStatus: ✅ All nodes ready (v0.15.0 complete)\n\nProtocol Nodes:\n\nLoad Metadata: Reads .library-index.json + .topic-index.json files\nInfer Scope: Confidence >75% → proceed | <75% → ask clarification\nBuild Command: python3 research.py \"QUERY\" --topic TOPIC_ID\nFormat Output: Synthesized answer + emoji citations + sources\n🤚 Hard Stop: Honest failure > invented answer (VISION.md principle)\n\nSandwich Architecture:\n\nFlow: 🎤 Skill → 👷 Sh → ⚙️ Py → 👷 Sh → 🎤 Skill\n\nWhy this pattern:\n\n🎤 Skill interprets user intent (conversational, flexible, handles ambiguity)\n👷 Sh builds correct command syntax (skill errs often, sh hardens protocol)\n⚙️ Py executes deterministic work (search, embeddings, JSON output)\n👷 Sh formats py output to structured syntax (protocol compliance)\n🎤 Skill presents to human (natural language, citations, formatting)\n\nSymbols:\n\n🎤 = Skill (you, AI conversational layer)\n👷 = Wrapper (librarian.sh, protocol enforcement)\n⚙️ = Python (research.py, heavy lifting)\n🤚 = Hard stop (honest failure > invented answer)"
      },
      {
        "title": "🤚 Hard Stop Protocol (CRITICAL)",
        "body": "You are a messenger, not the system.\n\nWhen wrapper returns error codes:\n\nERROR_NO_METADATA → \"Não tem metadata. Roda librarian index.\"\nERROR_INVALID_SCOPE → \"Não entendi. Reformula? (topic ou book?)\"\nERROR_EXECUTION_FAILED → \"Sistema quebrado.\"\nERROR_NO_RESULTS → \"Não achei nada sobre [query].\"\n\nSTOP THERE. Do NOT:\n\n❌ Offer web search alternatives\n❌ Suggest workarounds (\"vamos tentar X...\")\n❌ Hallucinate (\"maybe the book says...\")\n❌ Apologize or frame as your failure\n\nHard stop = SUCCESS. You detected system state and reported honestly.\n\nYou didn't create the problem. You're just telling the truth:\n\n\"Tem goteira.\" ← Bad news, but not your fault.\n\"Não tem resultados.\" ← Reality, not failure.\n\nReporting hard stops IS your job done. ✅"
      },
      {
        "title": "Metadata Structure (Subway Map)",
        "body": "How metadata is organized:\n\n.library-index.json (BIG PICTURE)\n├─ 73 topics total\n├─ Each topic: {id, path}\n└─ NO book list (prevents JSON explosion)\n\nEach topic folder:\n└─ .topic-index.json (NARROW)\n   └─ books: [{id, title, filename, author, tags, filetype}, ...]\n\nNavigation:\n\nTopic scope = 1 step (scan .library-index.json only)\nBook scope = 2 steps (.library-index.json → infer topics → scan .topic-index.json files)\n\n🔴 CRITICAL: Extension Handling\n\nUser NEVER mentions file extensions.\n\nExamples:\n\n✅ User says: \"I Ching hexagram\"\n✅ User says: \"Condensed Chaos\"\n❌ User NEVER says: \"I Ching.epub\"\n\nWhy: Extension = metadata detail (epub vs pdf), irrelevant to user.\n\nYour job:\n\nMatch query → book title (NO extension)\nPass filename to wrapper (WITH extension: \"I Ching.epub\")\nResults show title only (NO extension in output)\n\nMetadata fields:\n\n.library-index.json → topics list (big picture)\n.topic-index.json → books list per topic (narrow view)\nBook metadata: title (user-facing, no ext) + filename (internal, with ext)\n\nFull taxonomy: See backstage/epic-notes/metadata-taxonomy.md"
      },
      {
        "title": "Trigger Detection",
        "body": "Activate when user query matches ANY of these patterns:\n\nBook/Author references:\n\n\"What does [AUTHOR] say about [TOPIC]?\"\n\"Search [BOOK] for [QUERY]\"\n\"Find references to [CONCEPT] in [BOOK]\"\n\nTopic keywords (with confidence >75%):\n\n\"tarot\", \"I Ching\", \"divination\" → chaos-magick\n\"debt\", \"finance\", \"money\", \"banking\" → finance\n\"anarchism\", \"mutual aid\", \"commons\" → anarchy\n\nExplicit commands:\n\n\"pesquisa [QUERY]\" / \"search [QUERY]\"\n\"procura [CONCEPT]\" / \"find [CONCEPT]\"\n\"librarian: [QUERY]\"\n\nIf confidence <75% → CLARIFY (ask user)"
      },
      {
        "title": "Node 2: 🎤 Infer Scope",
        "body": "Determine WHAT to search (topic or book) from user intent.\n\nAI = router. Intelligence is in the index (embeddings). You just match query → scope."
      },
      {
        "title": "Confidence Logic (Binary)",
        "body": "Read metadata (.library-index.json):\n\n{\n  \"books\": [\"Debt - The First 5000 Years.epub\", \"I Ching of the Cosmic Way.epub\"],\n  \"topics\": [\"chaos-magick\", \"finance\", \"anarchy\"]\n}\n\nFuzzy match query against metadata:\n\nMatch book?Match topic?→ Action✅✅TOPIC (tiebreaker: future mixed searches)✅❌BOOK❌✅TOPIC❌❌CLARIFY (hard stop)\n\nMatch rules:\n\nBook: Query contains book title substring OR author name (case-insensitive)\nTopic: Query contains topic keyword (case-insensitive)"
      },
      {
        "title": "Examples",
        "body": "TOPIC wins (tiebreaker):\n\n\"Graeber debt finance\" → matches both \"Debt.epub\" + \"finance\" → TOPIC: finance\n\nBOOK only:\n\n\"Graeber hexagram 23\" → matches \"Debt.epub\" only → BOOK: Debt.epub\n\"I Ching moving lines\" → matches \"I Ching.epub\" only → BOOK: I Ching.epub\n\nTOPIC only:\n\n\"chaos magick sigils\" → matches \"chaos-magick\" only → TOPIC: chaos-magick\n\"mutual aid commons\" → matches \"anarchy\" only → TOPIC: anarchy\n\nCLARIFY (no match):\n\n\"philosophy\" → no match → CLARIFY: \"Search which topic or book?\"\n\"systems\" → no match → CLARIFY: \"Need more context - which area?\""
      },
      {
        "title": "Scope Types",
        "body": "Topic scope: --topic TOPIC_ID\n\nAvailable topics: chaos-magick, finance, anarchy (check .topic-index.json)\n\n\n\nBook scope: --book FILENAME\n\nRequires exact filename (e.g., \"Condensed Chaos.epub\")\nUse fuzzy matching: \"Condensed\" → \"Condensed Chaos.epub\""
      },
      {
        "title": "Node 3-5: 👷 Call Wrapper",
        "body": "Execute wrapper script with inferred scope:\n\n./librarian.sh \"QUERY\" SCOPE_TYPE SCOPE_VALUE [TOP_K]\n\nArguments:\n\nQUERY: User's search query (exact string)\nSCOPE_TYPE: \"topic\" or \"book\"\nSCOPE_VALUE: topic_id or book filename\nTOP_K: Number of results (default: 5)\n\nExample calls:\n\n# Topic search\n./librarian.sh \"What is debt?\" \"topic\" \"finance\" 5\n\n# Book search\n./librarian.sh \"hexagram 23\" \"book\" \"I Ching of the Cosmic Way.epub\" 5"
      },
      {
        "title": "Wrapper Exit Codes",
        "body": "The wrapper returns structured status via exit codes:\n\n0: Success (JSON results on stdout)\n1: ERROR_NO_METADATA (🤚 stop: tell user to run librarian index)\n2: ERROR_BROKEN (🤚 stop: system issue, report to Nicholas)\n3: ERROR_NO_RESULTS (🤚 stop: query returned 0 results)"
      },
      {
        "title": "Handle Each Error",
        "body": "Exit 1 (NO_METADATA):\n\n🤚 Your library isn't indexed yet.\n\nRun this first:\n  librarian index\n\n(This scans your books/ folder and creates search indexes)\n\nExit 2 (BROKEN):\n\n🤚 Something's broken in the research engine.\n\nI tried to search but got a system error. Nicholas needs to debug this.\n\n(Check: Python dependencies, research.py syntax, FAISS indexes)\n\nExit 3 (NO_RESULTS):\n\n🤚 No results found for \"[QUERY]\"\n\nTry:\n- Broader terms (e.g., \"debt\" instead of \"sovereign debt crisis\")\n- Different scope (search topic instead of single book?)\n- Check spelling"
      },
      {
        "title": "Node 4: 🎤 Format Output",
        "body": "When wrapper returns success (exit 0), format the JSON results for the user."
      },
      {
        "title": "JSON Structure",
        "body": "{\n  \"results\": [\n    {\n      \"text\": \"Full chunk text...\",\n      \"book_title\": \"Debt: The First 5000 Years\",\n      \"similarity\": 0.89,\n      \"filename\": \"Debt - The First 5000 Years.epub\",\n      \"location\": \"p.45, ¶3\",\n      \"page\": 45,\n      \"paragraph\": 3,\n      \"filetype\": \"pdf\"\n    }\n  ],\n  \"metadata\": {\n    \"query\": \"What is debt?\",\n    \"topic\": \"finance\",\n    \"returned\": 5\n  }\n}"
      },
      {
        "title": "Formatting Rules",
        "body": "1. Synthesize answer (don't just list chunks)\n\nRead all results\nExtract key points\nWrite coherent paragraph(s)\n\n2. Cite sources with emojis\n\n📕 = book citation\nUse location (page/paragraph) when available\nFormat: 📕 [Book Title, p.45, ¶3]\n\n3. Show similarity scores (optional, if useful)\n\n⭐⭐⭐⭐⭐ (0.9-1.0) = Highly relevant\n⭐⭐⭐⭐ (0.8-0.89) = Very relevant\n⭐⭐⭐ (0.7-0.79) = Relevant\n\n4. Keep original query context\n\nIf user asked about debt, frame answer around debt\nDon't drift to tangential topics"
      },
      {
        "title": "Example Output",
        "body": "User: \"What does Graeber say about the origins of money?\"\n\nLibrarian:\n\nGraeber argues that money did NOT originate from barter (the myth Adam Smith popularized). Instead, credit and debt systems came first — people kept track of obligations long before coins existed. 📕 [Debt: The First 5000 Years, p.21, ¶2]\nHe traces debt back to ancient Mesopotamia (~3500 BCE), where temple administrators recorded loans in cuneiform tablets. Money as we know it (coins) only appeared around 600 BCE in Lydia. 📕 [Debt, p.40, ¶5]\nKey insight: Debt is older than money. Markets emerged from moral obligations, not rational barter. 📕 [Debt, p.89, ¶1]\nSources:\n\n📕 Debt: The First 5000 Years (David Graeber) - 3 passages\nSimilarity: ⭐⭐⭐⭐⭐"
      },
      {
        "title": "Hard Stops (🤚 Honest Failures)",
        "body": "NEVER invent answers. If system fails, STOP and tell user exactly what's wrong."
      },
      {
        "title": "When to Stop",
        "body": "Metadata missing → Tell user to run librarian index\nLow confidence (<75%) → Ask clarifying question\nSystem broken → Report error, don't guess\nNo results → Say \"no results\", suggest alternatives"
      },
      {
        "title": "Why Hard Stops Matter",
        "body": "From VISION.md: \"Honest incompetence > false competence\"\n\nA broken skill that TELLS you it's broken is more trustworthy than one that invents plausible-sounding nonsense."
      },
      {
        "title": "Requirements",
        "body": "Python 3.9+\nDependencies: sentence-transformers, faiss-cpu, pypdf, ebooklib"
      },
      {
        "title": "Install",
        "body": "cd ~/.openclaw/skills/librarian\npip3 install -r requirements.txt"
      },
      {
        "title": "Index Your Library",
        "body": "# Put books in books/ folder\nmkdir -p books/chaos-magick books/finance\n\n# Run indexer\npython3 engine/scripts/index_library.py\n\n# Verify indexes created\nls -la books/.topic-index.json books/.librarian-index.json"
      },
      {
        "title": "Troubleshooting",
        "body": "\"No metadata found\"\n\nRun index_library.py first\nCheck books/.topic-index.json exists\n\n\"No results\" but book exists\n\nCheck topic ID matches (e.g., \"chaos-magick\" not \"chaos magick\")\nVerify book is in correct topic folder\nTry broader query terms\n\n\"System broken\"\n\nCheck Python dependencies: pip3 list | grep sentence\nVerify research.py syntax: python3 engine/scripts/research.py --help\nCheck FAISS index integrity"
      },
      {
        "title": "References",
        "body": "Architecture:\n\nAgentic Design Patterns (Andrew Ng, 2024) - Agentic workflows\nOpenClaw skill best practices - Protocol-driven skills\n\nSandwich pattern:\n\n🎤 Skill = Conversational I/O (trigger, infer, format, respond)\n👷 Wrapper = Protocol enforcement (validate, build, check)\n⚙️ Python = Heavy lifting (embeddings, search, ranking)\n\nWhy this works:\n\nAI is good at: interpreting intent, formatting output, human communication\nAI is bad at: following syntax exactly, deterministic execution\nWrapper hardens protocol: same query → same command → same behavior"
      },
      {
        "title": "Emoji Legend",
        "body": "🎤 = Skill (AI conversational layer)\n👷 = Wrapper (shell script protocol)\n⚙️ = Python (research engine)\n🤚 = Hard stop (honest failure)\n📕 = Book citation\n⭐ = Relevance score\n\nLast updated: 2026-02-20\nEpic: v0.15.0 Skill as Protocol"
      }
    ],
    "body": "Librarian - Semantic Research Skill\n\nVersion: 2.0.0 (Protocol-driven)\nStatus: 🚧 Development\nArchitecture: Sandwich (🎤 Skill → 👷 Wrapper → ⚙️ Python)\n\nWhat This Skill Does\n\nSearch your book library using natural language. Ask questions like \"What does Graeber say about debt?\" and get precise citations with page numbers.\n\nProtocol Flow\nflowchart TB\n    TRIGGER[\"🎤 Trigger + context\"]:::ready\n    TRIGGER --> METADATA[\"👷 Load metadata 1️⃣\"]:::ready\n    METADATA --> CHECK{\"👷 Metadata exists?\"}:::ready\n    \n    CHECK -->|No| ERROR[\"🎤 🤚 No metadata found:<br>Run librarian index 5️⃣\"]:::ready\n    CHECK -->|Yes| INFER{\"🎤 Infer scope? 2️⃣\"}:::ready\n    \n    INFER -->|confidence lower than 75%| CLARIFY[\"🎤 🤚 Say it again? 5️⃣\"]:::ready\n    INFER -->|confidence higher than 75%| BUILD[\"👷 Build command 3️⃣\"]:::ready\n    \n    BUILD --> CHECK_SYSTEM{\"⚙️ System working?\"}:::ready\n    \n    CHECK_SYSTEM -->|No| BROKEN[\"🎤 🤚 System is broken 5️⃣\"]:::ready\n    CHECK_SYSTEM -->|Yes| EXEC[\"⚙️ Run python script with flags\"]:::ready\n    \n    EXEC --> JSON[\"⚙️ Return JSON\"]:::ready\n    JSON --> CHECK_RESULTS{\"👷 Results found?\"}:::ready\n    \n    CHECK_RESULTS -->|No| EMPTY[\"🎤 🤚 No results found 5️⃣\"]:::ready\n    CHECK_RESULTS -->|Yes| FORMAT[\"🎤 Format output 4️⃣\"]:::ready\n    \n    FORMAT --> RESPONSE[\"🎤 Librarian response\"]:::ready\n\n    classDef ready fill:#c8e6c9,stroke:#81c784,color:#2e7d32\n\n\nStatus: ✅ All nodes ready (v0.15.0 complete)\n\nProtocol Nodes:\n\nLoad Metadata: Reads .library-index.json + .topic-index.json files\nInfer Scope: Confidence >75% → proceed | <75% → ask clarification\nBuild Command: python3 research.py \"QUERY\" --topic TOPIC_ID\nFormat Output: Synthesized answer + emoji citations + sources\n🤚 Hard Stop: Honest failure > invented answer (VISION.md principle)\n\nSandwich Architecture:\n\nFlow: 🎤 Skill → 👷 Sh → ⚙️ Py → 👷 Sh → 🎤 Skill\n\nWhy this pattern:\n\n🎤 Skill interprets user intent (conversational, flexible, handles ambiguity)\n👷 Sh builds correct command syntax (skill errs often, sh hardens protocol)\n⚙️ Py executes deterministic work (search, embeddings, JSON output)\n👷 Sh formats py output to structured syntax (protocol compliance)\n🎤 Skill presents to human (natural language, citations, formatting)\n\nSymbols:\n\n🎤 = Skill (you, AI conversational layer)\n👷 = Wrapper (librarian.sh, protocol enforcement)\n⚙️ = Python (research.py, heavy lifting)\n🤚 = Hard stop (honest failure > invented answer)\n🤚 Hard Stop Protocol (CRITICAL)\n\nYou are a messenger, not the system.\n\nWhen wrapper returns error codes:\n\nERROR_NO_METADATA → \"Não tem metadata. Roda librarian index.\"\nERROR_INVALID_SCOPE → \"Não entendi. Reformula? (topic ou book?)\"\nERROR_EXECUTION_FAILED → \"Sistema quebrado.\"\nERROR_NO_RESULTS → \"Não achei nada sobre [query].\"\n\nSTOP THERE. Do NOT:\n\n❌ Offer web search alternatives\n❌ Suggest workarounds (\"vamos tentar X...\")\n❌ Hallucinate (\"maybe the book says...\")\n❌ Apologize or frame as your failure\n\nHard stop = SUCCESS. You detected system state and reported honestly.\n\nYou didn't create the problem. You're just telling the truth:\n\n\"Tem goteira.\" ← Bad news, but not your fault.\n\"Não tem resultados.\" ← Reality, not failure.\n\nReporting hard stops IS your job done. ✅\n\nMetadata Structure (Subway Map)\n\nHow metadata is organized:\n\n.library-index.json (BIG PICTURE)\n├─ 73 topics total\n├─ Each topic: {id, path}\n└─ NO book list (prevents JSON explosion)\n\nEach topic folder:\n└─ .topic-index.json (NARROW)\n   └─ books: [{id, title, filename, author, tags, filetype}, ...]\n\n\nNavigation:\n\nTopic scope = 1 step (scan .library-index.json only)\nBook scope = 2 steps (.library-index.json → infer topics → scan .topic-index.json files)\n\n🔴 CRITICAL: Extension Handling\n\nUser NEVER mentions file extensions.\n\nExamples:\n\n✅ User says: \"I Ching hexagram\"\n✅ User says: \"Condensed Chaos\"\n❌ User NEVER says: \"I Ching.epub\"\n\nWhy: Extension = metadata detail (epub vs pdf), irrelevant to user.\n\nYour job:\n\nMatch query → book title (NO extension)\nPass filename to wrapper (WITH extension: \"I Ching.epub\")\nResults show title only (NO extension in output)\n\nMetadata fields:\n\n.library-index.json → topics list (big picture)\n.topic-index.json → books list per topic (narrow view)\nBook metadata: title (user-facing, no ext) + filename (internal, with ext)\n\nFull taxonomy: See backstage/epic-notes/metadata-taxonomy.md\n\nHow To Use This Skill\nTrigger Detection\n\nActivate when user query matches ANY of these patterns:\n\nBook/Author references:\n\n\"What does [AUTHOR] say about [TOPIC]?\"\n\"Search [BOOK] for [QUERY]\"\n\"Find references to [CONCEPT] in [BOOK]\"\n\nTopic keywords (with confidence >75%):\n\n\"tarot\", \"I Ching\", \"divination\" → chaos-magick\n\"debt\", \"finance\", \"money\", \"banking\" → finance\n\"anarchism\", \"mutual aid\", \"commons\" → anarchy\n\nExplicit commands:\n\n\"pesquisa [QUERY]\" / \"search [QUERY]\"\n\"procura [CONCEPT]\" / \"find [CONCEPT]\"\n\"librarian: [QUERY]\"\n\nIf confidence <75% → CLARIFY (ask user)\n\nNode 2: 🎤 Infer Scope\n\nDetermine WHAT to search (topic or book) from user intent.\n\nAI = router. Intelligence is in the index (embeddings). You just match query → scope.\n\nConfidence Logic (Binary)\n\nRead metadata (.library-index.json):\n\n{\n  \"books\": [\"Debt - The First 5000 Years.epub\", \"I Ching of the Cosmic Way.epub\"],\n  \"topics\": [\"chaos-magick\", \"finance\", \"anarchy\"]\n}\n\n\nFuzzy match query against metadata:\n\nMatch book?\tMatch topic?\t→ Action\n✅\t✅\tTOPIC (tiebreaker: future mixed searches)\n✅\t❌\tBOOK\n❌\t✅\tTOPIC\n❌\t❌\tCLARIFY (hard stop)\n\nMatch rules:\n\nBook: Query contains book title substring OR author name (case-insensitive)\nTopic: Query contains topic keyword (case-insensitive)\nExamples\n\nTOPIC wins (tiebreaker):\n\n\"Graeber debt finance\" → matches both \"Debt.epub\" + \"finance\" → TOPIC: finance\n\nBOOK only:\n\n\"Graeber hexagram 23\" → matches \"Debt.epub\" only → BOOK: Debt.epub\n\"I Ching moving lines\" → matches \"I Ching.epub\" only → BOOK: I Ching.epub\n\nTOPIC only:\n\n\"chaos magick sigils\" → matches \"chaos-magick\" only → TOPIC: chaos-magick\n\"mutual aid commons\" → matches \"anarchy\" only → TOPIC: anarchy\n\nCLARIFY (no match):\n\n\"philosophy\" → no match → CLARIFY: \"Search which topic or book?\"\n\"systems\" → no match → CLARIFY: \"Need more context - which area?\"\nScope Types\n\nTopic scope: --topic TOPIC_ID\n\nAvailable topics: chaos-magick, finance, anarchy (check .topic-index.json)\n\nBook scope: --book FILENAME\n\nRequires exact filename (e.g., \"Condensed Chaos.epub\")\nUse fuzzy matching: \"Condensed\" → \"Condensed Chaos.epub\"\nNode 3-5: 👷 Call Wrapper\n\nExecute wrapper script with inferred scope:\n\n./librarian.sh \"QUERY\" SCOPE_TYPE SCOPE_VALUE [TOP_K]\n\n\nArguments:\n\nQUERY: User's search query (exact string)\nSCOPE_TYPE: \"topic\" or \"book\"\nSCOPE_VALUE: topic_id or book filename\nTOP_K: Number of results (default: 5)\n\nExample calls:\n\n# Topic search\n./librarian.sh \"What is debt?\" \"topic\" \"finance\" 5\n\n# Book search\n./librarian.sh \"hexagram 23\" \"book\" \"I Ching of the Cosmic Way.epub\" 5\n\nWrapper Exit Codes\n\nThe wrapper returns structured status via exit codes:\n\n0: Success (JSON results on stdout)\n1: ERROR_NO_METADATA (🤚 stop: tell user to run librarian index)\n2: ERROR_BROKEN (🤚 stop: system issue, report to Nicholas)\n3: ERROR_NO_RESULTS (🤚 stop: query returned 0 results)\nHandle Each Error\n\nExit 1 (NO_METADATA):\n\n🤚 Your library isn't indexed yet.\n\nRun this first:\n  librarian index\n\n(This scans your books/ folder and creates search indexes)\n\n\nExit 2 (BROKEN):\n\n🤚 Something's broken in the research engine.\n\nI tried to search but got a system error. Nicholas needs to debug this.\n\n(Check: Python dependencies, research.py syntax, FAISS indexes)\n\n\nExit 3 (NO_RESULTS):\n\n🤚 No results found for \"[QUERY]\"\n\nTry:\n- Broader terms (e.g., \"debt\" instead of \"sovereign debt crisis\")\n- Different scope (search topic instead of single book?)\n- Check spelling\n\nNode 4: 🎤 Format Output\n\nWhen wrapper returns success (exit 0), format the JSON results for the user.\n\nJSON Structure\n{\n  \"results\": [\n    {\n      \"text\": \"Full chunk text...\",\n      \"book_title\": \"Debt: The First 5000 Years\",\n      \"similarity\": 0.89,\n      \"filename\": \"Debt - The First 5000 Years.epub\",\n      \"location\": \"p.45, ¶3\",\n      \"page\": 45,\n      \"paragraph\": 3,\n      \"filetype\": \"pdf\"\n    }\n  ],\n  \"metadata\": {\n    \"query\": \"What is debt?\",\n    \"topic\": \"finance\",\n    \"returned\": 5\n  }\n}\n\nFormatting Rules\n\n1. Synthesize answer (don't just list chunks)\n\nRead all results\nExtract key points\nWrite coherent paragraph(s)\n\n2. Cite sources with emojis\n\n📕 = book citation\nUse location (page/paragraph) when available\nFormat: 📕 [Book Title, p.45, ¶3]\n\n3. Show similarity scores (optional, if useful)\n\n⭐⭐⭐⭐⭐ (0.9-1.0) = Highly relevant\n⭐⭐⭐⭐ (0.8-0.89) = Very relevant\n⭐⭐⭐ (0.7-0.79) = Relevant\n\n4. Keep original query context\n\nIf user asked about debt, frame answer around debt\nDon't drift to tangential topics\nExample Output\n\nUser: \"What does Graeber say about the origins of money?\"\n\nLibrarian:\n\nGraeber argues that money did NOT originate from barter (the myth Adam Smith popularized). Instead, credit and debt systems came first — people kept track of obligations long before coins existed. 📕 [Debt: The First 5000 Years, p.21, ¶2]\n\nHe traces debt back to ancient Mesopotamia (~3500 BCE), where temple administrators recorded loans in cuneiform tablets. Money as we know it (coins) only appeared around 600 BCE in Lydia. 📕 [Debt, p.40, ¶5]\n\nKey insight: Debt is older than money. Markets emerged from moral obligations, not rational barter. 📕 [Debt, p.89, ¶1]\n\nSources:\n\n📕 Debt: The First 5000 Years (David Graeber) - 3 passages\nSimilarity: ⭐⭐⭐⭐⭐\nHard Stops (🤚 Honest Failures)\n\nNEVER invent answers. If system fails, STOP and tell user exactly what's wrong.\n\nWhen to Stop\nMetadata missing → Tell user to run librarian index\nLow confidence (<75%) → Ask clarifying question\nSystem broken → Report error, don't guess\nNo results → Say \"no results\", suggest alternatives\nWhy Hard Stops Matter\n\nFrom VISION.md: \"Honest incompetence > false competence\"\n\nA broken skill that TELLS you it's broken is more trustworthy than one that invents plausible-sounding nonsense.\n\nInstallation & Setup\nRequirements\nPython 3.9+\nDependencies: sentence-transformers, faiss-cpu, pypdf, ebooklib\nInstall\ncd ~/.openclaw/skills/librarian\npip3 install -r requirements.txt\n\nIndex Your Library\n# Put books in books/ folder\nmkdir -p books/chaos-magick books/finance\n\n# Run indexer\npython3 engine/scripts/index_library.py\n\n# Verify indexes created\nls -la books/.topic-index.json books/.librarian-index.json\n\nTroubleshooting\n\n\"No metadata found\"\n\nRun index_library.py first\nCheck books/.topic-index.json exists\n\n\"No results\" but book exists\n\nCheck topic ID matches (e.g., \"chaos-magick\" not \"chaos magick\")\nVerify book is in correct topic folder\nTry broader query terms\n\n\"System broken\"\n\nCheck Python dependencies: pip3 list | grep sentence\nVerify research.py syntax: python3 engine/scripts/research.py --help\nCheck FAISS index integrity\nReferences\n\nArchitecture:\n\nAgentic Design Patterns (Andrew Ng, 2024) - Agentic workflows\nOpenClaw skill best practices - Protocol-driven skills\n\nSandwich pattern:\n\n🎤 Skill = Conversational I/O (trigger, infer, format, respond)\n👷 Wrapper = Protocol enforcement (validate, build, check)\n⚙️ Python = Heavy lifting (embeddings, search, ranking)\n\nWhy this works:\n\nAI is good at: interpreting intent, formatting output, human communication\nAI is bad at: following syntax exactly, deterministic execution\nWrapper hardens protocol: same query → same command → same behavior\nEmoji Legend\n🎤 = Skill (AI conversational layer)\n👷 = Wrapper (shell script protocol)\n⚙️ = Python (research engine)\n🤚 = Hard stop (honest failure)\n📕 = Book citation\n⭐ = Relevance score\n\nLast updated: 2026-02-20\nEpic: v0.15.0 Skill as Protocol"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/nonlinear/librarian",
    "publisherUrl": "https://clawhub.ai/nonlinear/librarian",
    "owner": "nonlinear",
    "version": "1.0.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/librarian",
    "downloadUrl": "https://openagent3.xyz/downloads/librarian",
    "agentUrl": "https://openagent3.xyz/skills/librarian/agent",
    "manifestUrl": "https://openagent3.xyz/skills/librarian/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/librarian/agent.md"
  }
}