mapj-search

name: mapj-search description: > Aggregated multi-source TOTVS documentation search. Returns ranked hits from TDN, Centraldeatendimento, Zendesk CST, YouTube TOTVS and Central de Downloads in a single call. Use when: you need broad coverage across the TOTVS ecosystem in one query; you don't know which specific source has the answer; the user asked a natural-language question without specifying TDN/Zendesk/forum. Do NOT use when: you already know the source (use mapj tdn search / mapj confluence export for TDN-only refinement), or you need community-posts / agent-only features that require Zendesk session cookies (future Phase 5). Triggers: "search TOTVS", "find documentation about", "where does TOTVS document", "is there a TOTVS article on", "find AdvPL/Protheus/Datasul/RM how-to", "buscar documentación", "encontrar artigo", "what tutorials exist for". compatibility: No authentication required. Works against ti-services.totvs.com/cst/BUSCA. metadata: version: 2.0.0 language: en author: Mario Pereira tags: - totvs - search - aggregated - cst - tdn - zendesk - youtube capabilities: - aggregated-search - multi-source-fanout - filter-by-line - filter-by-produto - filter-by-language - filter-by-freshness - source-selection - filter-discovery - score-normalization - cross-source-dedup - forum-discourse-adapter - wordpress-adapter - po-ui-adapter - zendesk-direct-adapter related: - mapj-tdn-search - mapj-confluence-export

allowed-tools: Bash

mapj search — Agent Skill v1.0

Aggregated documentation search across the TOTVS ecosystem in a single call. Backed by POST https://ti-services.totvs.com.br/cst/BUSCA — an Elasticsearch front-end indexed with TDN articles, Zendesk help center articles (centraldeatendimento and totvscst), YouTube TOTVS channel and Central de Downloads, all in one corpus (cst_totvs) with comparable score.

No authentication required. Phase 1 only consults this aggregator; Phase 2+ will add direct Discourse (forum.totvs.io), WordPress (espacolegislacao) and PO UI adapters under the same envelope and the same fetch_url canonical ids.

Role

Eres un agente especializado en encontrar documentación TOTVS para responder preguntas técnicas. Tu primera elección debe ser mapj search cuando no sabés de antemano qué fuente tiene la respuesta — el endpoint CST agrega TDN + Central + Zendesk + YouTube + Downloads en una sola query con score numérico real, ahorrándote tener que probar fuente por fuente.

Quick Routing

Need to...
├─ Broad question, unknown source → mapj search "tu pregunta"
├─ Refinement on TDN only         → mapj tdn search "..." (CQL filters)
├─ Filter by product line         → mapj search "..." --lines protheus
├─ Filter by product (key/name)   → mapj search "..." --produtos ConSeg
├─ Spanish content                → mapj search "..." --lang es
├─ Drop YouTube hits              → mapj search "..." --include-youtube=false
├─ Restrict sources               → mapj search "..." --sources tdn,central
├─ Discover valid filters         → mapj search --list-filters
└─ Output for token efficiency    → mapj search "..." -o toon

Core Commands

# Basic — aggregated search (default 10 results, pt-br)
mapj search "NF-e inutilizar"

# Filter by product line (name OR id; auto-resolved with warning)
mapj search "ponto de entrada" --lines protheus

# Filter by product key or name
mapj search "automação fiscal" --produtos ConSeg

# Restrict sources
mapj search "AdvPL" --sources tdn,central --max-results 30

# Drop YouTube videos
mapj search "treinamento" --include-youtube=false

# Spanish-language results
mapj search "facturación electrónica" --lang es

# Date-based filter (drop items older than 1 year)
mapj search "reforma tributária" --freshness-days 365

# Discover valid lines/produtos before filtering
mapj search --list-filters

# Token-efficient output for downstream LLM
mapj search "NF-e" -o toon

Output Schema (Phase 1)

{
  "ok": true,
  "command": "mapj search",
  "result": {
    "query": "NF-e inutilizar",
    "total_found": 372519,                 // total in backend index
    "returned": 10,                         // after filters + max-results cap
    "sources_queried": ["tdn","central","youtube","downloads"],
    "execution_ms": 693,
    "items": [
      {
        "rank": 1,
        "source": "tdn",                    // tdn|central|cst_zendesk|youtube|downloads|forum|legislacao|po_ui|web
        "kind": "article",                  // article|post|video|download|spec|web_page
        "title": "NF-e - Inutilizar numeração de NF-e",
        "html_url": "https://tdn.totvs.com/pages/viewpage.action?pageId=66617420",
        "snippet": "Produto: NF-e ... Inutilizar numeração ...",
        "updated_at": "2018-05-22T12:05:25Z",
        "score_raw": 60.90828,              // backend score, comparable in batch
        "score_norm": 1.0,                  // [0..1] normalized; top hit = 1.0
        "fetch_url": "tdn:66617420"         // → feed to: mapj fetch <fetch_url>
      }
    ],
    "by_source": {
      "tdn":     {"hits": 6, "max_score": 60.9},
      "central": {"hits": 4, "max_score": 54.8}
    },
    "warnings": [
      "resolved --lines=\"protheus\" to id \"000006\" (TOTVS Linha Protheus)"
    ]
  }
}

fetch_url — the canonical id for follow-up fetch

Each item carries a fetch_url that is the stable identifier to retrieve the document in Phase 3 (mapj fetch <fetch_url>):

Sources without a stable id (legislacao, web in future) use the full HTML URL.

Examples

Example 1: Broad question, unknown source

Input: "How do I inutilizar an NF-e?" Command: mapj search "NF-e inutilizar" --max-results 5 Result: Aggregated hits from TDN and Central — pick the one with highest score_norm, then mapj fetch <fetch_url>.

Example 2: Filter by product line by name

Input: "ponto de entrada en Protheus" Command: mapj search "ponto de entrada" --lines protheus --max-results 10 Result: Warning resolved --lines="protheus" to id "000006", items filtered to Protheus line only.

Example 3: Discovery before filtering

Input: Not sure which lines exist Command: mapj search --list-filters Result: All 33 lines, 64 produtos, with their canonical ids. Use the id (or any substring of the name) in --lines.

Example 4: Token-efficient output

Input: Need to feed many results into an LLM context Command: mapj search "AdvPL" -o toon Result: Tabular YAML-like layout — typically 15-30% smaller than JSON for tabular results (measured with tiktoken on representative search payloads). On dense small-key catalogs (filters, spaces) the saving is <5%.

Filter Discovery: --list-filters

Before using --lines or --produtos with values you're unsure about, discover the canonical vocabulary:

mapj search --list-filters --output json

Returns:

{
  "ok": true,
  "result": {
    "lines": [
      {"id": "000006", "name": "TOTVS Linha Protheus"},
      {"id": "000007", "name": "TOTVS Linha Datasul"},
      // ... 33 total
    ],
    "produtos": [
      {"id": 268468234, "name": "Consultoria de Segmentos", "key": "ConSeg"},
      // ... 64 total
    ],
    "counts": {
      "lines": 33, "produtos": 64,
      "environments": 739, "versions": 339
    }
  }
}

Then pass any of:

• The exact id (e.g. --lines 000006)
• Any case-insensitive substring of the name (e.g. --lines protheus, --lines "linha rm")

The CLI auto-resolves and surfaces what it picked in result.warnings.

Source-Specific Tips

TDN (source: "tdn")

• These are Confluence pages. For follow-up actions like full-tree export, use mapj tdn search with CQL filters.

Central (source: "central")

• Zendesk articles. Public read-only; community posts require session cookies (Phase 5).

YouTube (source: "youtube")

• Phase 1 just lists them; Phase 4 will add mapj fetch youtube:<id> to grab the transcript via yt-dlp.

Downloads (source: "downloads")

• Often legacy patch bundles (".PTM" files). The html_url points to the customer portal which usually requires login (suporte.totvs.com/portal).

Success Criteria

• ok: true and exit code 0
• result.items is an array (possibly empty)
• If filters are active and no hits: result.warnings explains why
• result.items[*].fetch_url is non-empty and follows <source>:<id> or is an HTTPS URL
• Encoding is UTF-8 clean (no � characters anywhere)

Error Reference

Health and Observability

The command emits structured logs to stderr with traceId, component=cst, latency, and per-attempt fields when --log-level debug.

To verify the CST endpoint is reachable:

mapj search "test" --max-results 1

— if you get hits in <2s, the aggregator is healthy.

Phase Roadmap

Phase 1 (✅ DONE) — CST aggregator with line/produto filter discovery. Phase 2 (✅ DONE) — forum.totvs.io (Discourse), espacolegislacao.totvs.com (WordPress), po-ui.io (static dataset), Zendesk direct adapter for label refinement. Parallel fan-out goroutines with per-source 12s timeout. Cross-source URL dedup with source-priority + score-weighted ranking. Phase 3 — mapj fetch <fetch_url> returns clean Markdown with frontmatter for any source. Phase 4 — YouTube transcripts via yt-dlp + optional Brave Search API (--include-web flag) for "Google-like" results restricted to TOTVS domains. Phase 5 — Standalone MCP server (mapj mcp serve) exposing search_totvs_docs and fetch_totvs_doc tools over stdio JSON-RPC.

The envelope shape is stable across phases; only source / kind enums grow, and result.warnings flags missing capabilities.