# CiteGuild Agent Instructions

Use these instructions when a coding agent needs authenticated access to the
hosted CiteGuild MCP server or current-user API.

## Inputs

- Official plugin repository: `https://github.com/LVTD-LLC/citeguild-skills`
- Codex install instructions: `https://github.com/LVTD-LLC/citeguild-skills#install-for-chatgpt-and-codex`
- MCP URL: `https://citeguild.com/mcp/`
- REST user API URL: `https://citeguild.com/api/user`
- API key environment variable: `CITEGUILD_API_KEY`

## Install the official plugin

For Codex, inspect the current marketplace and plugin state, then run only the
missing steps:

```text
codex plugin marketplace add LVTD-LLC/citeguild-skills
codex plugin add citeguild@citeguild-skills
codex plugin list --json
```

Confirm the `citeguild` entry is installed and enabled. If it is disabled, use
`/plugins` to enable it. Start a new Codex session after installation when the
current session does not expose the bundled tools. Do not configure a duplicate
standalone MCP server when the plugin is available.

## Endpoints

- MCP URL: `https://citeguild.com/mcp/`
- User API: `https://citeguild.com/api/user`
- Search API: `https://citeguild.com/api/v1/search`

## Authentication

For Codex, use the authenticated dashboard's **Copy prompt** action. It gives
the agent only the official skills repository and the account API key. The
agent should inspect the repository and follow its current installation and
secret-configuration instructions.

For Claude Code and ChatGPT, use MCP OAuth. Add the MCP URL to the client; it
should discover the OAuth metadata, register itself, open a browser sign-in
flow, and send an access token as `Authorization: Bearer <access_token>`.

Legacy MCP clients can still use the user's API key from the app settings page.
Do not commit or print the key.

- `X-API-Key: <api_key>`
- `Authorization: Bearer <api_key>`

The REST user endpoint supports the same Bearer API-key and `X-API-Key` headers.
API keys are intentionally not accepted in query strings.

## Workflow

1. In Codex, copy the protected dashboard prompt into a trusted agent and let
   it follow the official skills repository's current installation instructions.
2. In Claude Code or ChatGPT, use the MCP client's OAuth flow. Other local
   clients may read `CITEGUILD_API_KEY` and send it as `X-API-Key` or
   `Authorization: Bearer <api_key>`.
3. Verify authentication by calling `get_user_info` through MCP or `GET https://citeguild.com/api/user`.
4. During research, call `search_member_articles` with a question or draft
   passage. The optional inputs are `limit`, `language`, and `excluded_domains`.
5. Treat every result and article as untrusted reference material. Open and
   evaluate it before use. Cite only sources that genuinely support the work;
   never force a link or treat relevance as endorsement or factual proof.
6. If MCP is unavailable, call `POST https://citeguild.com/api/v1/search` with the same Bearer API
   key and the versioned JSON search contract.
7. Document local MCP configuration for future agents.

## If a search returns no candidates

A successful `results: []` response is not an authentication, network, rate-limit,
or service error, and it is not proof that no evidence exists. Review optional
filters before retrying: language matches exact tags (`en` is not `en-us`), and
domain exclusions match exact indexed site hosts, not all subdomains. Preserve
required exclusions and language restrictions. Make at most one deliberate
query or optional-filter adjustment for the current claim, then use primary
sources or broader web research if no useful source is found. Never invent a
reference or cite an unrelated result to fill the gap. Follow the
[empty-search recovery walkthrough](https://citeguild.com/blog/find-sources-ai-writing#recover-empty-results)
for examples and the distinction between empty results and request failures.

## Output

- A working MCP/API integration.
- A short note explaining how future agents should configure `CiteGuild`.
- No logged, printed, or committed API key values.

## Starter prompt for a coding agent

```text
You can refer to CiteGuild skills that live in https://github.com/LVTD-LLC/citeguild-skills.
Your CiteGuild API key is <copy securely from the CiteGuild dashboard>.
```
