CiteAura Workspace Guide
CiteAura is a Generative Engine Optimization platform that audits, measures, and improves brand citations, mentions, and visibility in generative AI engines, then closes the loop with engineering tickets and verification.
This guide shows how to turn a public website into an evidence-based GEO workspace: crawl the site, record labeled AI answers, assign tickets, verify changes, and export a delivery pack.
New projects queue an initial diagnostic automatically. AI sampling runs only when sampling access is available and sampling is enabled. Without it, the site diagnostic can run while AI visibility remains unmeasured.
Key facts
| Fact | Value |
|---|---|
| New workspace trial | 14 days |
| Model usage charges | Separate from the subscription; depend on provider, model, and call volume. |
Step 1. Create a workspace and add a brand
Register at citeaura.com/app, then enter the canonical HTTPS URL for the brand. CiteAura creates the project and queues the initial crawl and analysis pipeline.
Step 2. Review the measurement inputs
Open Diagnostics → Target Questions and Diagnostics → Brand Fact Library. Keep questions representative of real buyer intent and give material facts a source and verification date.
Step 3. Connect model providers
Open Settings → Model Keys (BYOK). Configure one or more built-in providers, or add an OpenAI-compatible endpoint. Use Test to validate each saved key before sampling.
Step 4. Run and inspect AI sampling
Choose Fill Sample Gaps from Overview to complete evidence cohorts, or Sample Matrix Now from Monitor to start a full measurement run. Review the exact prompt, raw answer, sampling mode, citations, and cohort before interpreting any score.
Step 5. Execute, verify, and deliver
Prioritize evidence-backed tickets in Execution → Action Tickets, deploy the relevant assets, then run Verify Changes. Use Delivery → Client Delivery Packs to build the current handoff package.
Workspace Workflow
The workspace follows a repeatable measurement and execution loop. Each view has a distinct role; use the evidence from one stage as the input to the next.
| Stage | What happens | Primary view |
|---|---|---|
| Establish | Crawl the canonical site and derive the initial question bank, facts, and audit evidence. | Overview |
| Measure | Record model answers for a versioned question set and classify each sampling mode. | Monitor |
| Diagnose | Inspect technical extraction issues, observed framing, questions, and official facts. | Diagnostics |
| Execute | Assign action tickets, edit generated assets, and prepare outreach or publishing drafts. | Execution |
| Verify | Re-crawl the site, evaluate acceptance checks, and reopen regressed tickets when required. | Closed-Loop Verify |
| Deliver | Compile the latest audit, ticket, verification, comparison, and asset files into a ZIP package. | Delivery |
One active job per project: while a project job is queued or running, commands that start another job may remain disabled or return a conflict. Wait for completion or open the telemetry panel to inspect a failure.
Measurement Concepts
CiteAura records observations from a defined question set. Results describe that sample cohort; they are not a guarantee of how every user, model version, region, or future answer will behave.
Sampling modes
| Label | Evidence source | Interpretation |
|---|---|---|
| API · Model knowledge | A provider API response without live retrieval. | Measures parametric model knowledge for the submitted question. |
| API · Web-grounded retrieval | A provider API response with web retrieval enabled. | Can produce source URLs used in Citation Sources. |
| Manual · Product surface | A transcript captured from a consumer product interface. | Kept distinct from API observations because the product surface can behave differently. |
Core metrics
- Mention rate: the share of successful, eligible answers that mention the configured brand. Questions containing the brand name are excluded from this calculation.
- Reported rank: the matrix uses the median recorded brand position among qualifying mentions. Missing ranks remain unmeasured.
- Sample count: the number of observations supporting the displayed metric.
- Citation share: the share of captured source URL mentions attributed to a domain within web-grounded samples.
- Unmeasured: no qualifying observation is available. It does not mean zero visibility.
Question sets and cohorts
Changes to Target Questions create a different measurement input. Compare trends only when question scope, provider configuration, sampling mode, and market are sufficiently consistent. Raw answers and cohort labels are the audit trail behind aggregate metrics.
Measurement is not placement. Adding an API key pays the provider for measurement calls. It does not alter model weights, buy recommendations, or guarantee citations.
Model Keys & Providers
Workspace owners manage model keys. CiteAura supports ten built-in providers: OpenAI, Anthropic, Google, xAI, Perplexity, DeepSeek, Zhipu GLM, Doubao, Kimi, and MiniMax, plus custom OpenAI-compatible HTTPS endpoints. BYOK usage is billed by the provider; sampling availability depends on the project market and configuration.
1. OpenAI
- Visit the official OpenAI Developer Platform (platform.openai.com/api-keys).
- In the dashboard, click Create new secret key.
- Select your organization or project, assign permissions, and copy the secret key.
- In CiteAura, open Settings → Model Keys (BYOK) → OpenAI and paste the key.
2. Anthropic
- Visit the official Anthropic Console (console.anthropic.com).
- Navigate to API Keys and click Create Key.
- Name your key, copy the
sk-ant-...token, and paste it into CiteAura under Settings → Model Keys (BYOK) → Anthropic.
3. Google
- Visit the official Google AI Studio (aistudio.google.com/apikey).
- Click Create API key and choose an existing or new Google Cloud Project.
- Copy the generated
AIzaSy...key and paste it into CiteAura under Settings → Model Keys (BYOK) → Google.
4. xAI
- Visit the official xAI Console (console.x.ai).
- Navigate to API Keys in your team management console.
- Click Create API Key, set access permissions, copy the key, and paste into CiteAura under Settings → Model Keys (BYOK) → xAI.
5. Perplexity
- Visit the official Perplexity API Settings (perplexity.ai/settings/api).
- Ensure billing is active on your API account, then click Generate under API Keys.
- Copy the
pplx-...token and paste it into CiteAura under Settings → Model Keys (BYOK) → Perplexity.
6. DeepSeek
- Visit the official DeepSeek Platform (platform.deepseek.com/api_keys).
- Create an API key and copy the token.
- In CiteAura, open Settings → Model Keys (BYOK) → DeepSeek and paste the key. DeepSeek’s official API is parametric knowledge only; it does not enable live web search.
Custom OpenAI-compatible providers
- In Model Keys, choose Add Provider to configure a custom endpoint.
- Enter a provider name, the HTTPS API base URL, and the exact model ID. Do not append
/chat/completionsto the base URL. - Enter the API key and save. CiteAura tests the endpoint before retaining the configuration.
Key and data handling
- Saved API keys are encrypted at rest with AES-256-GCM and made available during authorized engine operations, then removed from that execution context.
- API responses expose masked key identifiers, not the full secret.
- CiteAura does not use workspace content to train its own models. Provider processing, retention, and training controls remain subject to the selected provider account and policy.
- Deleting a saved key prevents later jobs from loading it. It does not cancel running jobs or revoke the key at the provider; revoke it there when access must end immediately.
Cost control: provider-side quotas, budgets, and rate limits are the final control for BYOK spend. Configure them in each provider account before enabling scheduled monitoring.
Monitor Visibility & Citations
AI Visibility Matrix
The matrix separates results by provider and sampling mode. Compare mention rate, reported rank, eligible sample count, and measurement status within comparable cohorts. Use Sample Matrix Now to queue new sampling.
Open Raw AI Sample Answers & Citations before acting on an aggregate. The replay contains the exact question, answer, provider, mode, detected brand identity, and returned source URLs.
Citation Sources
This view counts only source URLs returned by web-enabled model samples. Parametric answers without URLs do not create citation evidence. Domain share is calculated within the captured cohort, not across the whole web.
Use Draft Outreach when a cited third-party domain is relevant and there is a factual contribution worth proposing. Treat the list as observed evidence, not a directory placement guarantee.
Competitor Benchmark
Add direct competitors to compare recommendation frequency in recorded answers. Keep the set small and commercially relevant. A competitor configured by a user is different from a competitor observed in model evidence; CiteAura preserves that distinction.
Diagnostics & Brand Inputs
Site-wide GEO Audit
Review crawlability, page roles, semantic structure, extraction blocks, and structured data. Page grades summarize applicable checks; skipped or non-applicable checks are shown separately. Use Re-run Audit after the public site changes.
Perception Gaps
Perception Gaps summarizes recurring descriptors found in recorded answers. It reflects sampled phrasing and does not independently decide whether a statement is factually correct. Compare it with the Brand Fact Library and raw answers.
Target Questions
The question bank defines what the model matrix measures. Include real discovery, comparison, category, and problem-oriented questions. Avoid near-duplicates and prompts written only to force the brand name into an answer.
Trend discipline: changing the question set changes the measurement basis. Record the question-set version and avoid treating two materially different cohorts as a strict before-and-after comparison.
Brand Fact Library
Maintain official claims used by generated content and delivery assets. Prefer a source URL and verification date for material claims. The library is a controlled input; it does not override contrary evidence returned by a model.
Action Tickets & Execution
CiteAura maps audit and sampling evidence to a standard ticket library. The current project total can change when evidence changes, users add project-specific tickets, completed items regress, or a rerun preserves customized work.
Action Tickets
- Prioritize by impact and effort, then open a ticket to review its rationale, target page, owner, requested update, and acceptance criteria.
- Assign an operational status only when it reflects the real implementation state.
- Attach decisions to the relevant question IDs so later verification remains explainable.
- Create a manual ticket when project evidence requires work outside the standard library.
Sampling Evidence Workbench
Use the Workbench to compare recorded answers for a selected question and inspect the citations available to each response. It is an evidence review surface, not a second measurement engine.
Assets & Templates
Generated project files can include machine-readable discovery content, structured data, deployment notes, and editable text assets. Review every claim and destination before saving or deploying an asset.
Media Outreach & Publishing Destinations
In Settings → Media Outreach, review pitch drafts and confirm sending through configured SMTP. In Execution → Publishing Destinations, export finished, approved assets to CMS drafts, webhooks, or an asset-only GitHub review PR (this uploads selected files from Assets & Templates and never merges automatically or edits existing source code). To modify your live codebase from audit tickets, run local prechecks, and auto-verify deployments, use MCP & Coding Agents instead.
Using /llms.txt
/llms.txt is an emerging machine-readable discovery convention, not a universal indexing standard. It can present official facts and links in a concise Markdown file, but support varies by crawler and provider.
- Review the generated file in Execution → Assets & Templates.
- Remove unsupported claims and confirm every URL is canonical and public.
- Deploy it at
https://example.com/llms.txtwith a successful text response. - Re-crawl and verify availability. Do not interpret availability as proof that a model consumed it.
Verification & Delivery
Closed-Loop Verify
Run verification after deploying website changes. It re-crawls and audits the site, then checks tickets against the latest audit and existing metrics. Results can be pass, fail, or manual review; failed checks can reopen completed tickets. Verification does not collect fresh AI answers.
- Deploy the selected ticket changes to the canonical public site.
- Open Execution → Closed-Loop Verify and choose Run Verification.
- Inspect the verification history and failed acceptance checks.
- Run a separate AI sample when you also need a fresh model-answer cohort.
Client Delivery Packs
Open Delivery → Client Delivery Packs and choose Build Diagnostic Pack. The downloadable ZIP contains the current diagnostic, tickets, evidence, and assets. Check whether it is a review, diagnostic, or implementation pack; templates and unmeasured results do not become deployment-ready simply by being packaged.
On Agency, an owner can configure Settings → White-Label Branding before building. Rebuild after material workspace changes. A diagnostic pack can be produced before implementation and verification are complete; its limitations remain disclosed.
MCP & Coding Agents
CiteAura exposes a remote Streamable HTTP Model Context Protocol (MCP) server at POST https://citeaura.com/api/v1/mcp. Unlike Execution → Publishing Destinations (GitHub PR), which only uploads finished, approved asset files for review, MCP connects Claude Code, Cursor, Codex CLI, or Antigravity so your agent can pull open action tickets and site audit defects, edit your existing codebase directly, precheck artifacts locally, and trigger live verification after deployment.
1. Token scopes and security
Only workspace owners can issue scoped integration tokens in MCP & Coding Agents in the left workspace navigation (also accessible from Settings → Model Keys). Tokens are displayed once at creation, stored as SHA-256 hashes, expire after 90 days by default, and are authenticated with Authorization: Bearer ca_.... Writing or verifying requires explicit opt-in scopes; read-only tokens remain strictly read-only.
| Scope | Allowed operations | Rate budget |
|---|---|---|
read |
List projects, inspect overview, pull tickets and audit gaps, read generated assets and brand facts, run local static prechecks, poll jobs, and read verification results. | 120 req / 60s per token |
tickets:write |
Includes read. Update ticket workflow status (such as doing or blocked) and append commit/PR notes attributed to the token in the ticket activity timeline. |
30 writes / 60s per token |
verify:run |
Includes read. Enqueue live re-crawl and automated ticket verification jobs against the canonical public site URL. |
5 runs / 300s per tenant |
2. Connect Claude Code, Cursor, Codex, or Antigravity
Create a token with the Coding Agent preset under MCP & Coding Agents to copy ready-to-paste snippets prefilled with your workspace URL, or use the templates below:
Claude Code
claude mcp add --transport http citeaura https://citeaura.com/api/v1/mcp \ --header "Authorization: Bearer YOUR_CA_TOKEN"
Cursor (.cursor/mcp.json)
{
"mcpServers": {
"citeaura": {
"url": "https://citeaura.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_CA_TOKEN"
}
}
}
}
Codex CLI (~/.codex/config.toml)
# export CITEAURA_MCP_TOKEN="YOUR_CA_TOKEN" [mcp_servers.citeaura] url = "https://citeaura.com/api/v1/mcp" bearer_token_env_var = "CITEAURA_MCP_TOKEN"
Antigravity (mcp_config.json)
{
"mcpServers": {
"citeaura": {
"serverUrl": "https://citeaura.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_CA_TOKEN"
}
}
}
}
3. Verify connection & invoke in chat
In Claude Code, run claude mcp list in your terminal or type /mcp inside a session to confirm citeaura is connected with all 16 tools and 2 prompt templates loaded.
Once connected, ask your agent in natural language across the three stages below:
# 1. Inspect projects, open tickets, and audit defects Use CiteAura MCP to list my projects, inspect open tickets and failing site-audit checks for project_id=1, and prioritize what needs fixing in this codebase.
# 2. Implement grounded fixes & precheck locally Use CiteAura MCP to read get_brand_facts and the top P0 ticket for project_id=1, mark it doing, update the matching files in this repo, and run precheck_artifact before I deploy.
# 3. Trigger live verification after deployment I deployed the changes to production. Use CiteAura MCP trigger_verify on project_id=1, poll until it completes, and report which tickets closed vs failed.
In Claude Code or IDE chat, you can also select the built-in MCP prompts fix_geo_tickets (arguments: project_id, optional ticket_id) or verify_deployed_fixes (argument: project_id) from the / menu, or attach read-only resources like citeaura://projects/{project_id}/facts.
4. Closed-loop workflow: fix, precheck, deploy, verify
- Inspect & ground: Call
get_project_overview,get_brand_facts, andlist_tickets(status="open"), then inspect affected URLs, failed role-aware checks, and linked assets withget_ticket_detail,get_site_audit, andget_generated_asset. - Track work & edit code: Mark the ticket
doingviaupdate_ticket, then update SSR HTML, Schema.org JSON-LD,robots.txt,sitemap.xml, orpublic/llms.txtin your repository using only verified brand facts. - Local static precheck: Before deploying, validate draft markup with
precheck_artifact(kind:llms_txt,jsonld,html_page, orcontent). Prechecks returnverification_mode: "local_precheck"and never close tickets. - Deploy & auto-verify: Deploy your changes to your live public site, then call
trigger_verify, pollget_job_statusuntil terminal completion, and inspectget_verify_resultfor newly closed tickets (was → now), regressions, and remaining evidence.
Verification guardrails: Tickets with acceptance.type = "auto" cannot be manually forced to done through update_ticket; only a passing live re-crawl closes them. Publishing /llms.txt also requires human-approved Brand Facts in the workspace before site.has_llms_txt passes verification.
5. Tool, prompt, and resource reference
| Primitive | Scope | Purpose |
|---|---|---|
list_projects, get_project_overview |
read |
Discover active workspace projects, audit coverage scores, open auto-verifiable ticket counts, and active jobs. |
list_tickets, get_ticket_detail |
read |
Pull prioritized Playbook tickets, acceptance expressions, failing URLs, prerequisites, linked assets, and historical evidence. |
get_site_audit, get_citation_readiness |
read |
Inspect site crawler signals (robots.txt, sitemap, llms.txt) and paginated role-aware page check failures. |
list_generated_assets, get_generated_asset, get_brand_facts |
read |
Read generated llms.txt, jsonld/*.json, HTML snippets, content drafts, and verified facts.md with publishability warnings. |
precheck_artifact |
read |
Run offline syntax and role-aware HTML/JSON-LD/llms.txt checks locally prior to deployment. |
update_ticket |
tickets:write |
Transition open tickets (for example doing or blocked), set owner, or attach commit/PR notes; manual-only tickets can be closed with evidence. |
trigger_verify, get_job_status, get_verify_result |
verify:run / read |
Enqueue live verification re-crawl jobs, track worker stage and logs, and inspect closed/reopened/still-failing ticket verdicts. |
get_visibility_report, get_prompt_research |
read |
Read labeled AI visibility reports and prompt-research fan-out candidates. |
fix_geo_tickets, verify_deployed_fixes |
Prompts |
Built-in MCP prompt templates and read-only resource URIs (citeaura://projects/{project_id}/overview|facts|assets/{path}). |
Workspace Administration
| Settings view | Use it for | Important behavior |
|---|---|---|
| Brand Settings | Update the canonical website URL used by future crawls. | Confirm redirects and domain ownership before changing it. |
| Automated Schedule | Run monitoring every 1, 7, 14, or 30 days. | Scheduled cycles consume plan allowance and provider quota. Verification remains an explicit step. |
| Team Members | Invite Owners, Editors, and Viewers. | Owners administer the workspace, Editors execute project work, and Viewers have read-only access. |
| Billing & Plans | Review subscription state, usage, limits, and billing interval. | BYOK provider charges are separate from the CiteAura subscription. |
| Data Isolation & Key Security | Project files are isolated per tenant and model keys are encrypted at rest with AES-256-GCM. | CiteAura exposes technical controls but is not currently SOC 2 certified. |
| Backup Snapshots | Owners can create and restore project-file snapshots when backup storage is configured. | Restore merges snapshot files into the project and can overwrite matching paths after confirmation. Files absent from the snapshot are retained; this is not a full rollback. |
FAQ
How to start a CiteAura diagnostic?
Create a workspace, add a public website, configure sampling access, and inspect labeled results. You can build a diagnostic pack before implementing fixes; run verification after deployment.
Does CiteAura guarantee AI mentions?
No. CiteAura does not guarantee AI mentions, rankings, or citations. It produces diagnosis, tickets, and verification evidence.
Jobs & Troubleshooting
Job states
- Queued: the command is waiting for a worker.
- Running: the worker is executing the displayed pipeline stage.
- Done: the task completed and the affected views can be refreshed.
- Failed: open telemetry for the recorded error. Use Retry Job when the action supports retry.
Common checks
| Symptom | What to check |
|---|---|
| Engine is Unmeasured | Confirm a key is configured and tested, the question bank is not empty, and the latest sample completed successfully. |
| No citation sources | Confirm the cohort includes web-grounded samples that actually returned source URLs. Parametric samples do not populate this view. |
| Provider authentication error | Re-test the key, provider account, model permission, custom base URL, and exact model ID. |
| Provider rate or quota error | Review provider-side billing, rate limits, and budgets before retrying. |
| Project command is unavailable | Check your role, active trial or subscription, usage limits, and any queued or running job. A project allows only one active job at a time. |
| Delivery pack looks outdated | Finish the latest audit, ticket, or verification job, then choose Build Diagnostic Pack. |
Crawler Edge Caching & Proxy Configuration
When robots.txt or discovery file updates fail to take effect, edge caches or proxy directive ordering are typically responsible:
Cloudflare Edge Purge: When using Cloudflare CDN, purge the path directly via Caching → Custom Purge for https://yourdomain.com/robots.txt, and set origin headers to Cache-Control: max-age=3600, must-revalidate.
Crawler Log Analysis
Inspect server access logs to confirm AI crawlers (GPTBot, OAI-SearchBot) are reaching your origin and receiving valid HTTP 200 responses:
When reporting a persistent failure, include the project, job ID, action, stage, and telemetry error. Do not include full API keys or access tokens.
Related Engineering Guides & Solution Hubs
For deep-dive implementation playbooks and platform evaluations beyond workspace administration, explore:
- Solution Hubs: AI Visibility Audit · For Brands · For Agencies · Measurement Methodology · Sample Report · Platform Comparisons
- Search Surface Modules: Google AI Overviews Optimization · Perplexity SEO · Answer Engine Optimization (AEO) · LLM Optimization · AI Brand Monitoring · AI SEO Tools
- Technical Field Notes: JSON-LD Schema for AI Search · How to Write Pages That AI Cites · Google AI Overviews Citation Guide · Top 20 Domains Cited by LLMs · AI Search Directory Listings Guide · AI Crawler Access Checklist