Build with AI - Qirtaas

These docs are built to be read by AI coding assistants (Claude Code, Cursor, Copilot, ChatGPT, …) as easily as by you. This page covers the machine-readable endpoints, the docs MCP server, and copy-paste prompts for the common integration jobs.

AI-readable docs

Every page on this site is available as plain markdown, plus two index files:

URL	What it is
`/llms-full.txt`	The entire documentation as one markdown file — paste or fetch this to give an AI the full picture.
`/llms.txt`	A short index of all pages with descriptions, for tools that fetch pages selectively.
Any page + `.md`	The raw markdown of a single page, e.g. `/get-started/quickstart.md`.

You can also use the contextual menu on any page (top-right of the page body) to copy it as markdown or open it directly in ChatGPT or Claude.

Docs MCP server

The documentation is exposed as an MCP server at https://docs.qirtaas.io/mcp, giving your assistant a search tool over these docs. To add it to Claude Code:

claude mcp add --transport http qirtaas https://docs.qirtaas.io/mcp

For Cursor or VS Code, use the contextual menu on any docs page — it installs the MCP server with one click.

Integration prompts

Paste one of these into your coding assistant, in your project’s repo. Each prompt points the assistant at the exact docs it needs; it will adapt the steps to your framework and backend.

Set up the editor

The Quickstart, as a prompt — token endpoint plus a mounted editor:

Integrate the Qirtaas rich-text editor (an embeddable editor for Islamic
scholarly writing) into this app.

First read https://docs.qirtaas.io/get-started/quickstart.md — follow it,
adapting the code to this project's framework and backend.

In short:
1. Install the package matching the frontend: @qirtaas/react, @qirtaas/vue,
   or @qirtaas/core (vanilla).
2. Add a backend endpoint that exchanges the QIRTAAS_API_KEY env var for a
   short-lived embed token via POST https://api.qirtaas.io/v1/embed/tokens/
   with {"external_user_id": <the authenticated user's id>}. Gate it with
   the app's existing auth; derive external_user_id from the session, never
   from the request body.
3. Mount the editor with getToken wired to that endpoint, inside a container
   with a bounded height.

Hard rules: the qrt_sk_ secret key must never reach the browser — the
frontend only ever sees embed tokens. If any detail is unclear, consult
https://docs.qirtaas.io/llms-full.txt rather than guessing the API.

Add a notes feature

Full create / list / edit / delete on top of the setup above (the document creation and reading tutorials):

Add a notes feature to this app using Qirtaas: signed-in users write rich
documents, see them in a list, reopen them, read them cleanly, and delete
them. Qirtaas is the notes backend — no new tables in this app.

Read these two tutorials first and follow them, adapting to this project:
- https://docs.qirtaas.io/tutorials/document-creation.md
- https://docs.qirtaas.io/tutorials/document-reading.md

Key points from the docs:
- The only backend change is a token endpoint minting embed tokens from the
  QIRTAAS_API_KEY env var (never expose the key to the browser).
- Create a shared client with createQirtaasClient({ getToken }); use
  listDocuments() / deleteDocument() for the list, and the editor and
  renderer components for compose and read views.
- Mount the editor without a documentId to lazily create a document; record
  the id from onDocumentCreated. Remount (key) when switching documents.
- The editor needs a bounded-height container; mount only one embed at a
  time when their auth sources differ.

Gate reads behind your access control

Let other signed-in users read documents when your app allows it (the access control tutorial):

Documents in this app are authored with Qirtaas. Add gated cross-user
reading: another signed-in user may read a document only if this app's own
access check passes.

Read https://docs.qirtaas.io/tutorials/access-control.md first and follow
it, adapting to this project's backend and ACL.

In short:
1. Store a pointer to each document's qirtaas_doc_id alongside the domain
   object it belongs to.
2. Add a backend endpoint that authenticates the caller, runs the access
   check, and only then returns a local HMAC-SHA256 signature:
   hex(HMAC_SHA256(QIRTAAS_SIGNING_SECRET, "<document_id>|<exp>")) with an
   exp about an hour out. Never sign before the check passes, and never
   sign ids taken unchecked from the request.
3. Mount the renderer with getSignature wired to that endpoint; on an
   invalid_signature error, fetch a fresh signature and remount.

The signing secret stays in backend env only — it is as sensitive as the
API key.

Add a draft/publish lifecycle

Stable published versions while authors edit privately (the draft and publish tutorial):

Documents in this app are authored with Qirtaas and read through signed
renderer reads. Add a draft/published lifecycle: readers always see a
stable published version while the author edits a private draft, and
publishing is atomic.

Read https://docs.qirtaas.io/tutorials/draft-and-publish.md first and
follow it, adapting to this project.

The pattern: draft and published are two documents, not a flag. Keep two
pointers (qirtaas_doc_id for published, draft_doc_id for the
work-in-progress); derive the publication state from the pointers instead
of storing a status column. Only ever sign qirtaas_doc_id for readers.
Publishing promotes draft_doc_id into qirtaas_doc_id in one transaction;
revising clones the published document with duplicateDocument() and edits
the clone; the replaced document is deleted after promotion.

Teach your own repo about Qirtaas

If Qirtaas is a permanent part of your app, add this to your repo’s AGENTS.md (or CLAUDE.md) so every future AI session gets it right without being told:

## Qirtaas
- Qirtaas is the embedded rich-text editor. Docs index:
  https://docs.qirtaas.io/llms.txt (append `.md` to any docs URL for raw
  markdown; full docs at https://docs.qirtaas.io/llms-full.txt).
- The qrt_sk_ API key and the signing secret live in backend env only and
  must never reach the browser. The frontend only ever sees short-lived
  embed tokens minted by our token endpoint.
- The editor fills its container — always give it a bounded height. The
  renderer sizes to its content.
- Mount the editor without documentId to lazily create a document; record
  the id from onDocumentCreated. Remount with a key when switching
  documents.
- Cross-user reads use per-document HMAC signatures minted by our backend
  after its own access check — never mint another user's embed token.

​AI-readable docs

​Docs MCP server

​Integration prompts

​Set up the editor

​Add a notes feature

​Gate reads behind your access control

​Add a draft/publish lifecycle

​Teach your own repo about Qirtaas