English · Español
Cited is in early development and not ready for production. What you can run today is the core: it turns a
folder of documents into citable passages, finds them again with a hybrid search and answers with the passages it
found, every claim numbered as a citation. Read the status table before you promise anything to anyone.
Why Cited
- Only your documents. Ingestion reads the files you point it at, and nothing else: no web, no model memory,
nothing invented.
- Every passage keeps its source. Document, heading and position travel with the text, so a reader can open the
document and land on the passage instead of trusting a summary.
- Talk to it. Cited answers with the passages it found and numbers every claim, in writing and out loud: the
microphone of the public site opens a voice agent built on the same documents, and the owner creates that agent in
one click from the panel.
Status
Every row is either available today or planned, and each planned row names the change that delivers it.
| Capability | State | Spec or change |
|---|
| Ingestion of PDF, DOCX, Markdown and text with limits | Available | knowledge-search |
| Hybrid search: full text and vectors, fused with Reciprocal Rank Fusion | Available | knowledge-search |
| Local libSQL or Turso, and embeddings by API or Ollama | Available | knowledge-search |
| Answers with citations from any model provider, spend limits | Available | answering |
| The keys of the AI in the panel, encrypted and tested before saving | Available | provider-settings |
| The panel: the setup, the business, the documents and the conversations | Available | admin-panel |
| The guided setup: from zero to a published answer in four steps | Available | owner-setup |
| Public chat of the business, with the widget any site can embed | Available | public-chat |
| Voice agent with ElevenLabs, created in one click | Available | voice-agent |
How it works
From a folder of documents to a cited passage.
flowchart LR
A[Ingest: PDF, DOCX, MD, TXT] --> B[Passages with their heading]
B --> C[libSQL: FTS5 and native vectors]
C --> D[Reciprocal Rank Fusion]
D --> E[Answer with numbered citations]
D --> F[Web widget]
D --> G[Voice agent]
See it work
Ask a question. Get the passage and where it came from.
The image is drawn by scripts/render-readme-graphics.mjs from the output of the commands in the quick start, so it
cannot show a result the code does not produce: the same corpus, the same search and the same answer with its
citation.
The public chat, as it looks today. This one is not drawn: it is a real capture of / with a question answered and
the citation open, taken by scripts/render-readme-captures.mjs from the application served by npm run start with
the sample corpus, the deterministic providers and the sample business (Café La Horquilla, color #1F5F4A) saved in the
panel, so the chat wears its band.
And the owner manages it from the browser. The panel of /admin walks the owner from nothing to a published
answer in four steps: connect your AI, add your information, try it, publish it. Each step opens in its place and
proves itself before the next, and the panel stores the business, its logo and its documents. It opens in English, with
the switch English | Español in its header, and it is served by the same application as the questions.
docs/owner-guide.md is the walk of the owner, step by step and in both languages, with the captures of every screen;
docs/admin.md explains the screens, the routes, the store and the rules of the logo. Both captures are real runs of
the built application, taken by the end-to-end suite with the deterministic providers.
Roadmap
What runs today, and what comes next.
The changes of the plan arrive in this order: the voice with ElevenLabs, already in the repository, then the shared
design system, then the hardening, then the deploys and the docs.
Voice
Talk to your documents.
The microphone button of the public site and of the widget opens the voice panel: the Orb, the state in words, the live
transcript with the written question echoed once, and the citation chips named by document and section. The session
speaks to the agent the owner creates with one button of the panel, and that agent answers through
/api/voice/tool from the same documents and the same pipeline as the written chat. The key of ElevenLabs never
reaches the browser: the document asks this server for a signed URL of fifteen minutes, and the day has a cap of
minutes. docs/voice-agent.md explains the one-click agent, the two languages, the allowlist and the cap.
The picture below is a real capture of the panel at 1440 px, taken by scripts/render-voice-captures.mjs over the
build of the test SDK, which is the build the browser suite drives:
Works with your agent
Cited is also a server of the Model Context Protocol, so the agent you already use can search the documents of the
business and answer from them, with the same honest refusal when they do not hold the answer.
CITED_MCP_TOKEN=<a long random token> npm start
Two read-only tools are exposed. cited_search returns the passages with their document, their section, their position
and their text, and it never calls a model, so a search spends nothing. cited_ask walks the same pipeline as the
public chat and answers with numbered citations, or with the refusal.
| Agent | Verified on 2026-10-09 against a local Cited |
|---|
| DeepSeek Harness (MCP configuration) | Called cited_search and answered with a citation; configuration, step-10-4 evidence. |
| DeepSeek Harness (native plugin) | Selected cited_ask for a natural English question and answered with its own cited passage; transcript, compatibility evidence. |
| Claude Code | it connected and listed the tools |
| Codex | it connected and listed the tools |
| Hermes Agent (MCP configuration) | Called mcp__cited__cited_search for a natural question and answered 380 pesos with its citation; configuration, plugin at hermes-cited. |
| Hermes Agent (native plugin) | Verified on 2026-10-10. In cited mode the plugin writes the answer from the chosen document line, with its source and the mark [1], and a question the documents do not cover gets the fixed refusal. No "Verified by Cited" seal yet: Hermes exposes no delivery contract the plugin could vouch for. Plugin, , . |
Install the native plugin with dsh plugin add github:RonnieGex/dsh-cited.
docs/mcp.md carries the exact configuration for each one and for curl. The token travels in the
Authorization: Bearer header, and the server is off until you declare it.
The graphic quotes the exact first English answer paragraph and its own cited_ask guarantee passage. Markdown is rendered; the transcript keeps every call and the complete raw answer. 3 of 3 English questions received a supported guarantee citation from an English document. The earlier batch behind the Spanish example scored 2 of 3, including one English question that missed the Spanish price passage; Cited refused, and the agent wrongly claimed the price was absent. Keyword search without embeddings can miss a Spanish passage when asked in English. English outcomes, Spanish-example outcomes and verification details document the evidence and limits.
Quick start
Two commands prepare the corpus and one asks for an answer. No key is needed: the deterministic providers run
offline.
git clone https://github.com/RonnieGex/cited.git
cd cited
npm ci
cp .env.example .env
EMBEDDINGS_PROVIDER=fake npm run ingest -- samples/
EMBEDDINGS_PROVIDER=fake npm run search -- "¿Cuánto cuesta una afinación de bicicleta?"
EMBEDDINGS_PROVIDER=fake CHAT_PROVIDER=fake npm run ask -- "¿Cuánto cuesta una afinación de bicicleta?"
npm run dev
The template of the environment has every value empty on purpose, so the three commands of the corpus carry the
deterministic providers in front: fake runs offline and needs no key, for the embeddings and for the chat. To keep
it for the whole session, write EMBEDDINGS_PROVIDER=fake and CHAT_PROVIDER=fake in .env once and drop them from
the commands. The last command serves the app on http://localhost:3000, and POST /api/ask is the same answer over
HTTP.
The output of the three commands, on the sample corpus:
$ EMBEDDINGS_PROVIDER=fake npm run ingest -- samples/
ingested README.txt (txt, no pages, 1 passages)
ingested bike-workshop-policies.md (md, no pages, 5 passages)
ingested cafe-la-horquilla.md (md, no pages, 4 passages)
ingested notas-del-negocio.txt (txt, no pages, 1 passages)
documents 4, passages 11, skipped 0, store .data/katalis.sqlite, 30 ms, rss 130 MB
$ EMBEDDINGS_PROVIDER=fake npm run search -- "¿Cuánto cuesta una afinación de bicicleta?"
question: ¿Cuánto cuesta una afinación de bicicleta?
store: .data/katalis.sqlite
1. cafe-la-horquilla.md [Precios] position 2 score 0.032522
Precios - Espresso: 35 pesos. - Café de olla: 45 pesos. - Pan dulce del día: 30 pesos. - Afinación de bicicleta: 380 pesos. - Cambio de cámara: 120 pesos.
2. cafe-la-horquilla.md [Políticas] position 3 score 0.032522
Políticas Aceptamos efectivo y tarjeta. El taller recibe bicicletas hasta una hora antes del cierre. Si una reparación necesita refacciones, avisamos por teléfono antes de empezar.
3. notas-del-negocio.txt [no heading] position 0 score 0.031746
Café La Horquilla — notas del negocio Dirección: avenida central, frente al parque. Sin estacionamiento propio, pero hay uno público a media cuadra. Formas de pago: efectivo, tarjeta de débito y crédito. No aceptamos cheques ni transferenci
4. cafe-la-horquilla.md [Café La Horquilla] position 0 score 0.030331
Café La Horquilla Somos un café y taller de bicicletas en el centro de la ciudad. Abrimos de martes a domingo.
5. bike-workshop-policies.md [Guarantee] position 4 score 0.015625
Guarantee Every repair carries a 90 day guarantee on the work. Parts carry the guarantee of their maker. Bring the ticket; without it we can still look up the repair by the frame number.
6. bike-workshop-policies.md [Bookings and cancellations] position 1 score 0.015385
Bookings and cancellations A repair booking is free. Cancel or move your appointment at least 24 hours before the agreed time and there is no charge. A late cancellation costs 50 pesos, and a dropped appointment costs the full estimate.
7. bike-workshop-policies.md [Groups and events] position 3 score 0.015152
Groups and events We host a Saturday ride that leaves the shop at 9:30. Groups of more than 8 people should write to us a week ahead so we can arrange a mechanic and a second guide.
8. bike-workshop-policies.md [Bike workshop policies at Café La Horquilla] position 0 score 0.014925
Bike workshop policies at Café La Horquilla Everything a customer needs to know before leaving a bicycle with us.
8 results, 4 ms, rss 94 MB
$ EMBEDDINGS_PROVIDER=fake CHAT_PROVIDER=fake npm run ask -- "¿Cuánto cuesta una afinación de bicicleta?"
question: ¿Cuánto cuesta una afinación de bicicleta?
store: .data/katalis.sqlite
status: answered
answer: Respuesta del proveedor de prueba: - Afinación de bicicleta: 380 pesos. [1]
citations:
[1] cafe-la-horquilla.md [Precios] position 2 lead 0
Precios - Espresso: 35 pesos. - Café de olla: 45 pesos. - Pan dulce del día: 30 pesos. - Afinación de bicicleta: 380 pesos. - Cambio de cámara: 120 pesos.
citations 1, 38 ms, rss 102 MB
The store lives in .data/katalis.sqlite, which git ignores. docs/search.md explains the schema, the chunking and
the ranking, and docs/answering.md the prompt, the citations, the providers and the guards.
Requirements
- Node 24, never older than 24.15 (
.nvmrc, engines)
- npm 11 or newer
- gitleaks for the commit hook, and Playwright Chromium for the browser tests, only if you contribute
Configuration
The variables the owner sets, what each one is for, and whether the code reads it today.
| Variable | What it is for | Read today |
|---|
EMBEDDINGS_PROVIDER | the embeddings provider: openai, ollama or fake | yes |
EMBEDDINGS_BASE_URL | base URL of the OpenAI-compatible embeddings API | yes |
EMBEDDINGS_MODEL | name of the embeddings model | yes |
EMBEDDINGS_API_KEY | key of the embeddings provider | yes |
EMBEDDINGS_DIMENSIONS | optional override of the vector size of the provider | yes |
EMBEDDINGS_BATCH | how many texts one request to the embeddings provider carries, 32 by default; lower it for a provider that accepts fewer, like 16. A value that is not a positive integer keeps 32 | yes |
OLLAMA_BASE_URL | base URL of a local Ollama, http://localhost:11434 by default | yes |
DATABASE_URL | path of the local libSQL file, .data/katalis.sqlite by default | yes |
TURSO_DATABASE_URL | URL of a remote libSQL database; it wins over the local file | yes |
TURSO_AUTH_TOKEN | token of the remote database, required when the URL is remote | yes |
CHAT_PROVIDER | the chat provider of the answers: openai, anthropic, gemini, deepseek, groq, openrouter, ollama, lmstudio or fake | yes |
CHAT_MODEL | optional model of the chat provider; without it each one uses its default | yes |
OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY | the key of the chosen chat provider, and of no other | yes |
LMSTUDIO_BASE_URL |
A row marked no is a name the repository already reserves and no code reads yet. No key has a value in this
repository, and .env is ignored by git.
Security
Keys live only in the environment of the server. They never reach the browser and they are never stored in the
database. The threat model is docs/security.md; a vulnerability is reported privately, as SECURITY.md says, never
in a public issue. The repository has carried no commercially licensed font file since its first commit.
Contributing
Cited is specified before it is coded: every change is an OpenSpec change with a proposal, its spec deltas, a design
and a task list with its evidence. Read docs/katalis-sdd-standard.md and
docs/openspec-tasks-mandatory-steps.md, then CONTRIBUTING.md.
Before a pull request, run the same checks the pipeline runs:
npm run typecheck
npm run lint
npm test
npm run build
npm run test:e2e
npm run audit:high
npm run secrets:scan
npm run openspec:validate
License
Apache-2.0, with a LICENSE file and a NOTICE file that carries the attribution. A fork keeps the
notice.
