find-editorial-citations

Find Editorial Citations

Find sources that genuinely improve the user's work. Treat CiteGuild as a focused member corpus, not a replacement for a broad search engine.

Workflow

1. Extract a focused search query from the topic, passage, claim, or draft. Preserve the user's meaning and avoid sending confidential or unnecessary text.
2. Ask for the user's own domain only when it cannot be inferred and excluding it materially matters. Pass known owned domains as exact values in excluded_domains or repeated --exclude-domain flags.
3. Choose one available transport:
   • For OpenClaw, Hermes, shell agents, or scripts, prefer the citeguild CLI when it is installed.
   • In a client exposing CiteGuild MCP tools, call search_member_articles.
   • Otherwise, call the versioned REST endpoint POST https://citeguild.lvtd.dev/api/v1/search.
4. Start with 10 results. Increase the limit or try one narrower query only when the first pass is insufficient.
5. Rank candidates by direct topical and claim-level relevance. Prefer a smaller set of strong matches over filling a quota.
6. Present each useful candidate with its title, canonical URL, domain, and a short explanation of what it could support.
7. If the user is drafting content, recommend a citation only when the source materially supports the surrounding claim. Inspect the article before representing its contents when the search result alone is insufficient.

All three transports use the same v1 search contract: query is required; limit is 1–50; language is optional; and up to 20 exact excluded domains are allowed.

CLI

Keep the key in CITEGUILD_API_KEY. Never pass it as a flag or place it in a URL or config file.

Check configuration and authentication without revealing the key:

citeguild config status
citeguild auth status

For agents and scripts, request stable JSON. Put options before the query:

citeguild search --json --limit 10 \
  --language en \
  --exclude-domain my-site.example \
  "How do Django transaction commit hooks work?"

Use -- before a query that begins with a hyphen. Diagnostics go to stderr. A JSON failure includes code, message, retryable, exit_code, and when available request_id and retry_after_seconds. Do not install or upgrade the CLI unless the user asks; use MCP or REST when the command is unavailable.

MCP

Call search_member_articles with:

• query: question, topic, claim, or draft passage
• limit: 10 initially
• language: optional language tag
• excluded_domains: optional exact domains owned by the user

Use get_user_info only when authentication or subscription state needs verification.

REST API

Send the API key from CITEGUILD_API_KEY as either Authorization: Bearer or X-API-Key. Never put it in a query string.

curl --fail-with-body --silent --show-error \
  https://citeguild.lvtd.dev/api/v1/search \
  -H "Authorization: Bearer $CITEGUILD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"How do Django transaction commit hooks work?","limit":10,"language":"en","excluded_domains":["my-site.example"]}'

The success response contains contract_version: "v1" and results. Each result has article_id, title, canonical_url, domain, excerpt, relevance, language, and last_seen_at.

Guardrails

• State that results come from opted-in CiteGuild member articles, not the whole web.
• Never describe a candidate as verified, authoritative, or endorsed solely because CiteGuild returned it.
• Never promise a backlink, placement, ranking gain, or reciprocal link.
• Do not add irrelevant citations to manufacture an exchange. Editorial relevance wins.
• Do not imply that finding or citing a member article obligates its owner to cite back.
• Do not fabricate titles, URLs, claims, or source contents.
• Use broader web search or independent verification only when the user separately requests it or the task genuinely requires it; distinguish those results from CiteGuild candidates.

Authentication and errors

For CLI, REST, and API-key MCP access, use CITEGUILD_API_KEY. In Claude Code and ChatGPT, prefer the MCP client's OAuth flow unless the client is configured separately with an API key. Never hardcode, print, log, or commit a credential.

Handle transport errors consistently:

• 401: the credential is missing, invalid, or revoked.
• 403 with subscription_required: explain that an active subscription is required and stop.
• 422: correct the request contract.
• 429: honor Retry-After or retry_after_seconds.
• 503: preserve the query and suggest retrying rather than substituting invented results.

Output

Lead with the number of strong matches. For each match, return:

• linked article title and domain
• the claim or section it may support
• one-sentence relevance rationale
• any verification caveat

Say clearly when no result is sufficiently relevant.